Swashbuckle.aspnetcore: Document Issues

[grahamehorner]

I'm using Swashbuckle for the first time in a new ASP.NET core project; I prefer to use the RouteAttribute to map my API methods; the resulting generated documentation is not correct; optional routing elements show as path parameters that are marked as required? and with a data type that is not as detailed in the route attribute?

[HttpGet, Route("~/repository/entities/{entityIdentity:guid?}")]
public async Task<IActionResult> GetRepositoryEntity([FromRoute]Guid entityIdentity)

appears as

GET /repository/entities/{entityIdentity}

parameter
entityIdentity required path string

[domaindrivendev]

Swagger doesn't support optional path parameters

[grahamehorner]

Thanks for pointing this out; I understand would be that although not supported as part of the Swagger standard as documentation shows; the optional path parameter is at the end of the URI and this could be omitted when creating the swagger document creating multiple methods for the above example; would this be a good solution/work around to the swagger standard constraint.

How would swashbuckle/swagger be used to document odata for example, given odata has optional path parameters ?

[hmvs]

I think we should generate multiple endpoints/methods in this case.
@domaindrivendev what do you think about it?

[domaindrivendev]

What if there's 3 optional parameters - are we going to generate 8 operations to cover every possible combination???

[grahamehorner]

IMHO optional path parameters should only occur once at the end of a path. However a API method may have multiple paths. I think the main issue is that the api documentation (although correct for swagger) is incorrect as the path parameter is optional and therefore confusing to developers, may be the definition could be augmented with a generated general comment about the optional path parameters?

[hmvs]

In our case we have optional exactly last "path parameter".
@domaindrivendev we can probably start from that case. but in general it's probably what we should do. generate all the variants.

[erendrake]

this service contract doesnt require a change to Swashbuckle. Just have two endpoints, one with the parameter and one without :). Asking Swashbuckle to assume that it always should create operations for you like this is bound to confuse.

it should also be possible to write a schema filter to accomplish this without modifying the main package

[domaindrivendev]

closing as I agree with @erendrake