Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Add Description to ProducesResponseType (and others) for better OpenAPI document creation#58193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
captainsafia merged 25 commits intodotnet:mainfromsander1095:main
Oct 29, 2024

Conversation

sander1095
Copy link
Contributor

@sander1095sander1095 commentedOct 1, 2024•
edited
Loading

Add Description to ProducesResponseType (and other types) for better OpenAPI documents in Controllers

  • You've read theContributor Guide andCode of Conduct.
  • You've included unit or integration tests for your change, where applicable.
  • You've included inline docs for your change, where applicable.
  • There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Description

This pull request introduces the concept of adding OpenAPI's description to responses returned by ASP.NET Core. The changes include adding aDescription property to response metadata interfaces, classes, and attributes, as well as updating related tests.

As discussed in#55656 , Minimal API's are not (or minimally) addressed in this PR. This should instead be built in#57963 (which I would love to work on in the future!)

Fixes#55656

…structor and static methods to ProducesResponseTypeMetadata for correct description overloads
… commentAlso removed new constructors based on Safiaś comment
@ghostghost added the old-area-web-frameworks-do-not-use*DEPRECATED* This label is deprecated in favor of the area-mvc and area-minimal labels labelOct 1, 2024
@dotnet-policy-servicedotnet-policy-servicebot added the community-contributionIndicates that the PR has been added by a community member labelOct 1, 2024
@sander1095
Copy link
ContributorAuthor

sander1095 commentedOct 1, 2024•
edited
Loading

Hey@captainsafia, ASP.NET Core team and community!

I'm extremely excited to be able to create this PR! I'm dedicating this to the .NET and OpenAPI community, and I shouldn't forget to mentionhacktoberfest as well! I'd love to get this merged or marked as accepted in the month of October, so keep the PR feedback coming!

I've been working on this for a while since talking to Safia about it at the MVP Summit 2024, and I'm very grateful for the opportunity.

Now, let's talk about some details 😁.

The state of the PR

I believe the PR is coming along nicely, but I find it difficult to say if it isdone. I would need help from the ASP.NET Core team or community to get the following answered:

  • How can I test these changes? I have added unit tests, but because I do not know how I can test this functionally in an ASP.NET Core project, I do not know what I still might need to do.
    • I couldn't find any docs about this, so perhaps it'd be useful to add some documentation about this in the future?
  • How canSwashbuckle.AspNetCore,NSwag andMicrosoft.AspNetCore.OpenAPI benefit from this change? Are there code changes needed on their side, if so, how do we coordinate this? Library authors, let me know if I can help!
  • I've already mentioned this in the PR description, but I believe we also need to get feature parity on the Minimal API side (Allow OpenAPI's response descriptions to be set using Minimal API #57963). However, this still needs some discussion as implementing it could apparently lead to source incompatibility issues. I'd love assistance with knowing how we will tackle this; after that I'd love a crack at implementing it!

Andfinally:

Please let me know what other changes need to be made to make this work functionally! Again, my goal is to get this to an accepted (or even merged!) state in october, if possible!

@sander1095
Copy link
ContributorAuthor

@dotnet-policy-service agree

@mkArtakMSFTmkArtakMSFT added area-networkingIncludes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions and removed old-area-web-frameworks-do-not-use*DEPRECATED* This label is deprecated in favor of the area-mvc and area-minimal labels labelsOct 2, 2024
@sander1095
Copy link
ContributorAuthor

Hi@mkArtakMSFT and@adityamandaleeka ! When can I expect a review and response to my comment with questions? I am very excited to get started :)

Copy link
Member

@captainsafiacaptainsafia left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Great start! We'll also want to update the OpenAPI implementation to respect this new property. The code for constructing OpenAPI responses is locatedhere. Tests for this area arehere.

sander1095 reacted with hooray emoji
@sander1095
Copy link
ContributorAuthor

Hey@captainsafia! Thanks so much! I will look into this as soon as possible.

@sander1095
Copy link
ContributorAuthor

sander1095 commentedOct 9, 2024•
edited
Loading

Hi@captainsafia ! I've implemented your suggestions, please see the new commit and let me know if there's anything I can still do!

Copy link
Member

@captainsafiacaptainsafia left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

LGTM! Thanks for adding tests and the M.A.OpenApi changes.

sander1095 reacted with hooray emoji
@captainsafiacaptainsafia merged commitd7130a2 intodotnet:mainOct 29, 2024
27 checks passed
@dotnet-policy-servicedotnet-policy-servicebot added this to the10.0-preview1 milestoneOct 29, 2024
captainsafia pushed a commit that referenced this pull requestFeb 11, 2025
…API document creation (#58193)* Started adding Description to several attributes* Add new properties to unshipped apis* Some more progress of adding Description in some places* Small improvements based on API review comments* Added missing modifier to property* Make changes in unshipped.txt so the http project builds* Add Description to OpenApiRouteHandlerBuilderExtensions and extra constructor and static methods to ProducesResponseTypeMetadata for correct description overloads* Changed code to follow overload rules and fix compile issues* Fix minor typo* Remove code from OpenApiRouteHandlerBUilderExtensions based on Safiaś commentAlso removed new constructors based on Safiaś comment* Fix incorrect XML Comment* Fixed some more Public API issues* Add unit test* Add some more unit tests* Remove unnecessary set from interface* Remove unnecessary change in public api shipped file* Also update unshipped file so the build succeeds!* Apply the new Description in response models
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@captainsafiacaptainsafiacaptainsafia approved these changes

@halter73halter73Awaiting requested review from halter73halter73 is a code owner

@brunolins16brunolins16Awaiting requested review from brunolins16

@BrennanConroyBrennanConroyAwaiting requested review from BrennanConroyBrennanConroy is a code owner

Assignees

@captainsafiacaptainsafia

Labels
area-networkingIncludes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractionscommunity-contributionIndicates that the PR has been added by a community memberfeature-openapi
Projects
None yet
Milestone
10.0-preview1
Development

Successfully merging this pull request may close these issues.

Add Description to ProducesResponseType (and others) for better OpenAPI documents
5 participants
@sander1095@captainsafia@adityamandaleeka@amcasey@mkArtakMSFT
[8]ページ先頭
©2009-2025 Movatter.jp