Add OpenAPI/Swagger support to minimal actions

[halter73]

• Ideally done using purely endpoint metadata
• Might be done by leveraging Mvc.ApiExploer and implementing IApiDescriptionProvider
• Otherwise, needs design

[JamesNK]

I added Swashbuckle support using endpoint metadata for gRPC HTTP API

See: https://github.com/aspnet/AspLabs/tree/002b32674e5a4ff306158618f9d0789707e70753/src/GrpcHttpApi/src/Microsoft.AspNetCore.Grpc.Swagger

[ghost]

Thanks for contacting us.
We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[JamesNK]

Initial thoughts:

• Layering is an issue. Minimal actions are in Http.Extensions and Routing. Meanwhile, the ApiExplorer that Swagger integrates with is in Mvc.Abstractions. We don't want to have Http or Routing have a dependency on abstractions. That either means:

  • Recreating ApiExplorer that is independent of MVC (ApiExplorer itself depends on many MVC types like ActionDescriptor. Realistically a lot of Mvc.Abstractions would need to be created for this). If we did this then either swagger libraries like Swashbuckle would need to be extended to support it, or we would need to provide a wrapping over the top of it which populates the existing MVC ApiExplorer using data from the new MVC-less ApiExplorer.
  • Or a new project is created that depends on Route+Http and Mvc.Abstractions that glues them together (this is what I did with gRPC)

• We need to figure out what a minimal action actually looks like. Right now RequestDelegateFactory is taking the delegate and is applying logic to it to create an opaque RequestDelegate. Either we:

  • Extend RequestDelegateFactory so it turns some kind of model of the request delegate along with the request delegate itself. e.g. how its parameters map to their sources, how its return type is formatted/run. This is good because there is one source of truth about binding and the model.
  • Duplicate much of the factory's logic in a new type that is responsible for generating a model. I worry about duplication and two types going out of sync.

• If we recreate ApiExplorer+Mvc.Abstractions then the metadata about the minimal action could be a descriptor from this new thing. If we don't then we'll need a metadata descriptor that lives in routing/http.extensions that we figure out and then it is mapped to MVC's ActionDesciption.

@halter73 @davidfowl

[bradygaster]

Notes from our chat:

• need to provide non-XML-docs method of allowing metadata customization. We'd need to satisfy the absolute minimum OpenAPI v2 metadata to pass a validator
• okay to optimize for attributes for commentary/metadata over XML doc comments
• planning on supporting OpenAPI v2 at first, V3 will come later
• need to support customization of description and operationId
• operationId should match the method name by default

[YohanSciubukgian]

@bradygaster is there any issue to track progress on OpenApi v3 support ?

[bradygaster]

This repository would be the best spot. @halter73 do you think a separate issue for supporting v3 would be good so folks who care could follow it on their own and keep up?

[halter73]

This issue didn't track any work that was specific to any version of OpenAPI/swagger. It's Swashbuckle that takes the ApiExplorer metadata and turns it into OpenAPI/swagger output. It looks like they already support v3 looking at their github. Same for NSwag apparently.

I haven't tested either with v3 though, because I don't even know what I'd be looking for. Are there any new features we'd be able to take advantage of?

[bradygaster]

Good point @halter73 - if you're using either one of the major OpenAPI outputters, Swashbuckle or NSwag, they both support the output of all the various formats so you should be covered.