mattfrear/Swashbuckle.AspNetCore.Filters

Provide string[] via param different than on a property (improve documentation)

Hypenate opened this issue · 3 comments

Hypenate commented

Via params

        /// <summary>
        /// Get items by channel type
        /// </summary>
        /// <param name="channeltype" example="'email">Channels to filter on</param> <-- fails 
        /// <param name="channeltype" example="'['email']">Channels to filter on</param> <-- fails 
        /// <param name="channeltype" example="'[email]">Channels to filter on</param> <-- fails
        /// <param name="channeltype" example='["email"]'>Channels to filter on</param> <-- works
        /// <param name="channeltype" example="[&quot;email&quot;]">Channels to filter on</param> <-- works
        /// <response code="200">Ok</response>
        [HttpGet("channels", Name = "get-restrictions-by-channel")]
        [ProducesResponseType(typeof(ResponseWrapper<RestrictionBaseResponseModel>), StatusCodes.Status200OK)]
        public async Task<IActionResult> GetRestrictionsByChannel([FromQuery] string[] channeltype) { }

I also have a model, and there the following works:

        /// <summary>
        /// The channels this restriction applies to.
        /// </summary>
        /// <example>["email"]</example>
        public string[] Channels { get; set; }

It would be nice that this would be documented, it took my quite some time to figur this one out :)

mattfrear commented

XML examples is part of Swashbuckle.AspNetCore and not part of this project. The relevant section is here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

You are welcome to add to the documentation for that project by submitting a PR to that project.

Hypenate commented

I can 't do a PR for this repo.
image

Shall I create a fork?

mattfrear commented