Describe new client code generation Swagger features

[Rick-Anderson]

Copy from #8460 by @dougbu - we like to open doc issues from the doc page so they show up in the Feedback section of the doc.

General

https://docs.microsoft.com/en-ca/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1 covers the current state of client code generation in ASP.NET Core web sites. However, we're working to give customers simple ways to annotate their project files for automated code generation during every build (as source API descriptions change) and that should also be documented.

Note tooling for the new experience isn't going to happen immediately. The initial documentation should focus on manual edits to .csproj files.

Issues with Existing Topics

Does not cover work described in dotnet/aspnetcore#4896 and its sub-issues.

CC

@glennc

---

Document details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: f34eea37-51a4-6227-f5ed-6501624ad045
• Version Independent ID: 2994cf60-0cb7-afa2-20b8-7e2b1117f964
• Content: ASP.NET Core Web API help pages with Swagger / Open API
• Content Source: aspnetcore/tutorials/web-api-help-pages-using-swagger.md
• Product: aspnet-core
• GitHub Login: @RSuter
• Microsoft Alias: scaddie

[dougbu]

Should have mentioned in my original comment: The new feature will give end users many customization options. The documentation should cover MSBuild properties and item metadata they can set to affect code generation.

End users may also customize web sites that can generate API descriptions (as described in the next-level "Getting started with" pages). In this case, the optional settings control defaults for how a tool run from a consuming project will retrieve API descriptions.

[glennc]

You can now get an example of this working e2e using NSwag, but it isn't going to be completely RTM for 2.2. I think the best we can do here is start working on this doc first thing after the 2.2 ships as we will RTM it while we work on 3.0.

[aidapsibr]

I'd love to see more docs around NSWAG for dotnetcore CI scenarios (msbuild preferably, but CLI would be ok).

Additionally, the problem details support such as what happens out of the box if anything, how should I set it up, how does OpenAPI and ApiExplorer learn from that, does NSWAG support this model, do I use the Extensions dictionary or inherit and add properties?

IMO these two experiences, along with docker work being done really empower micro-service design.

[RicoSuter]

I'd love to see more docs around NSWAG for dotnetcore CI scenarios (msbuild preferably, but CLI would be ok).

I think we shouldn't add too much specific NSwag documentation here - just add links to the NSwag project wiki. This way it is much easier to keep the docs up-to-date and consistent...

[dougbu]

7c22abe gets us closer but need partner releases using the latest features to complete this work.

[cremor]

Is there a way to get this issue to show up in the feedback section of Develop ASP.NET Core apps using OpenAPI tools?

I was already in the process of writing an issue that this feature should be described in way more detail when I remembered this issue here. It would be good if readers of that page didn't get the idea that that's all that can be said about the feature.

[Rick-Anderson]

@cremor the issue can be tied to at most one page. I created and closed #15165 - which shows up on the closed issues tab of that page. Feel free to edit that closed issue.

[jkone27]

updates on this one? thorough and detailed documentation on OpenApiReference would be very much appreciated 👍

[Tim-Hodge]

Also looking for some updated docs on this - is OpenApiReference the recommended way for automated generation within csproj, or should I be looking elsewhere?

[Rick-Anderson]

Thank you for contacting us. Due to a lack of activity on this discussion issue we're closing it in an effort to keep our backlog manageable. If you believe there is a concern which hasn't been addressed, please file a new issue.