dotnet
ProducesResponseType should support setting a Description
Is there an existing issue for this?
- [X] I have searched the existing issues
Is your feature request related to a problem? Please describe the problem.
I am trying to use ASP.NET Core's [ProducesResponseType] to properly define my OpenAPI definition. The OpenAPI spec contains a Description that can be set for each response, which is very useful if you want to explain why a specific status code is returned.
You can not set the Description using [ProducesResponseType], so you need to use NSwag/Swashbuckle's SwaggerResponse which DOES roughly the same thing as [ProducesResponseType], but this can't be mixed with the cleaner looking, generic supporting [ProducesResponseType].
Having to use NSwag/Swashbuckle's specific attributes locks you into that library, whereas ProducesResponseType is library-agnostic and therefore my preferred approach.
Describe the solution you'd like
I would like to be able to use [ProducesResponseType] (and the other ones like [ProducesDefaultResponse]) and specify a Description like so:
[ProducesResponseType<User>(StatusCodes.Status200OK, Description = "A description of this response")]
This shouldn't be too tough to implement and if the .NET team would like to see this implemented, I wouldn't mind trying to create a PR for this, which is an exciting opportunity for me!
Additional context
No response
Thanks for the link, @gfoidl .
I see @captainsafia commented that the .NET team is not looking to make changes to [ProducesResponseType]. Instead, a developer should use Microsoft.AspNetCore.OpenApi. However, if I check that PR and look at the docs, this is only used by/supported by Minimal API's.
[ProducesResponseType] is used by Controllers and Actions, and I believe Microsoft.AspNetCore.OpenApi can't be used there to add descriptions to endpoints. I'd be dissapointed if Minimal API's gets new features (like OpenAPI descriptions) when they aren't ported back to Controllers, which has more "market share" compared to Minimal API's.
Therefore, I would like to propose that [ProducesResponseType] gets extended with the Description property regardless :).
If the .NET team does not agree, I'd love to hear more about their recommended solution to add Descriptions to Controller Actions.
@sander1095 Are you still interested in submitting an API proposal for this one?
Also, I believe the new built-in OpenAPI support will support the DescriptionAttribute on types so we could possibly use that as an avenue. However, it would be limited to applying descriptions on the response type itself.
I'll move this to the backlog for now but happy to take a look at an API proposal or an alternative solution if you're still eager here. 😄
Hi @captainsafia ! Thanks for the message :)
I'm definitely interested. I've been working on it some time back and have been busy with conferences so I didn't have a lot of time.
You can see my progress here. So far, it's not that much, but I suspect it isn't a whole lot of work. I believe the mapping of the new Description property may be something that needs to be done by the library authors (NSwag, Swashbuckle, Microsoft.OpenAPI)? Please correct me if I'm wrong.
https://github.com/sander1095/aspnetcore
I also had some difficulty getting the project to run locally, even when following the guidelines. I'll try again. I hope to have some time in the next 2 weeks to look further into this!
Also, I believe the new built-in OpenAPI support will support the DescriptionAttribute on types so we could possibly use that as an avenue. However, it would be limited to applying descriptions on the response type itself.
Gotcha. I think that Description on ProducesResponseType would still have its place, though, to allow people to easily decorate their OpenAPI paths with a description. :)
I've been working on it for a while longer, and I believe I could need some more guidance. I'm (obviously) quite unfamiliar with aspnetcore's codebase and I seem to find quite a lot of code that is related to API explorer/OpenAPI. I'm unsure in what sort of places I might need to make changes and what the impact is.
Any tips would be welcome. How I can easily debug the changes I'm making to see progress, or some boundaries so I know where to put the initial focus? I'd also gladly hop on a call sometime to talk more about all of this; whatever works best for the team!
PS: When building with Visual Studio 2022 Enterprise preview (after following the docs/BuildFromSource.cmd) I get the following error: Unable to resolve the .NET SDK version as specified in the global.json located at C:\projects\Personal\aspnetcore\global.json. However, when I run build.cmd things seem to work better. Any guidance to get the build to work in VS, or is this unsupported?
However, when I run build.cmd things seem to work better. Any guidance to get the build to work in VS, or is this unsupported?
You may have to configure Visual Studio to support running against preview SDKs. You should be able to do it if you go to Tools > Options > Environment > Preview Features, and make sure that "Use previews of the .NET Core SDK is checked".
Any tips would be welcome. How I can easily debug the changes I'm making to see progress, or some boundaries so I know where to put the initial focus? I'd also gladly hop on a call sometime to talk more about all of this; whatever works best for the team!
The first thing that we'll want to do is create an API proposal for the change. You can read more about the API proposal process here.
For the proposal, we'll want to add a Description property to the IProducesResponseTypeMetadata interface and then flow it through to to ProducesResponseTypeMetadata.
We'll also want to update the Produces method overloads in our extensions class.
The above should provide coverage for minimal APIs. We'll also want to provide the same support for MVC. Things are a lot more interesting there because MVC's produces attributes tend to play a role in components other than OpenAPI but I think adding a description to IApiResponseMetadataProvider and implementers should do the trick.
Hey @captainsafia . I've created a proposal here: #55656 . Perhaps we can work together on getting the issue into a api-ready-for-review state?