"Controller-based API" tutorial expects Swagger, but swagger isn't present by default

[diiq]

Description

One of the very first steps listed in this tutorial is "The Swagger page /swagger/index.html is displayed. Select GET > Try it out > Execute."

But today, the project template uses OpenAPI and not swagger, so the provided URL is a 404, and will only show a blank window without swagger or swashbuckle being installed.

I'm sure this tutorial worked when it was written -- thanks for writing it! -- but without changes it no longer gets new users even as far as successfully demonstrating the initial template, so 90% of it goes to waste.

Page URL

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

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

Metadata

• ID: 583ae3e7-5915-f22b-e54c-6c100cf2a7da
• Service: aspnet-core
• Sub-service: tutorials

Related Issues

[wadepickett]

@diiq, you are correct, this tutorial needs an update. Thanks for pointing it out. It is now scheduled for a rewrite/recode.

[timdeschryver]

Hello @wadepickett I can also help with this if you want.
I just need some guidance on how the team wants to move forward with the testing sections.
For example, we can write a Visual Studio (using http files) and Visual Studio Code (using Swagger, but showing how to set it up) sections for the testing strategy, similar to the Minimal Api Docs.

Sorry for the pings, I have some time left and I browsed through the issue list 😅. But, I don't want to give you additional work. Feel free to say no.

[Rick-Anderson]

@timdeschryver feel free to email me if you mention me and I don't respond within 2 business days.

[wadepickett]

Hello @wadepickett I can also help with this if you want. I just need some guidance on how the team wants to move forward with the testing sections. For example, we can write a Visual Studio (using http files) and Visual Studio Code (using Swagger, but showing how to set it up) sections for the testing strategy, similar to the Minimal Api Docs.

Sorry for the pings, I have some time left and I browsed through the issue list 😅. But, I don't want to give you additional work. Feel free to say no.

Sorry @timdeschryver, I just saw this. It was already being done. There is a PR in review which started as a community member contribution more than a week ago. I was scheduled to hit this one this week but ended dropping other work and hitting this one early since a PR was already started which touched on the tip of the iceberg for changes that needed to occur.

The note above about "For .NET 9+ we use OpenAPI, we're getting rid of Swagger.", needs some clarification. We are no longer using the Swashbuckle tools to create the OpenAPI specification. We are using the Microsoft.AspNetCore.OpenApi package for OpenAPI support instead. However, a number of tools including Scalar, SwaggerUI, etc can be used to read that specification and add interactivity for viewing and ad-hoc testing. See the latest on that here: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/using-openapi-documents?view=aspnetcore-9.0#use-swagger-ui-for-local-ad-hoc-testing