search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.57k stars 25.31k forks source link

Create Web API: v9 update v8 sample update and rewrite for VSC version OpenAPI UI gen #33001

Open wadepickett opened 2 months ago

wadepickett commented 2 months ago

Description

Update to .NET 9.

Also, the app sample to 8.0 needs to be updated and the v8 version of the doc point to it.

Instruction for older versions needs to indicate the version of the Nuget package to select, or simply state to choose the latest version available to match the project target.

Update the code and content for the VSC tab version to use a recommended OpenAPI UI gen with v9 such as scalar or move to curl.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-9.0&tabs=visual-studio#scaffold-a-controller-1

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/tutorials/first-web-api.md

Document ID

95f2549e-29f9-e31a-b4d0-432b971643ff

Article author

@wadepickett

Associated WorkItem - 291122

wadepickett commented 3 weeks ago

Note: Might be partially blocked on this one as I am trying to complete it at the end of the sprint, until I have an OK on using an OpenAPI UI generation package such as scalar.

Looking for a decision here in the disucssion here: #32477#issuecomment-2313663431

So far I have done the pre-work for versioning, and new versions of the app sample to the point of adding a UI generation package for OpenAPI and updating the content down to the point section for testing out the API.

Instructions and screenshots from the test section on down for the VSC tab version will have to be rewritten. We were using swaggerUI before.

If using the Scalar.AspNetCore package for generating UI, it would be pointed to the OpenAPI generated .json output (This would be enabled for the dev environment only as was also pointed out here: Work with OpenAPI documents | Microsoft Learn

wadepickett commented 3 weeks ago

Per discussion https://github.com/dotnet/AspNetCore.Docs/issues/32477#issuecomment-2313663431 , since we already have a swaggerUI demonstrated with version 8 for folks to refer to, we will go scalar for v9.

However, with just one more day left of this monthly sprint (August) I am not going to be able to finish this one and we have higher priority security related triaging to still get through first. So moving this to September.