Updated first-web-api tutorial

[lukekaese]

Hi,

A colleague of mine recently took his first steps with C# and ASP.NET Core, specifically in .NET 9. Unfortunately, he became quite frustrated while following this tutorial:

Create a web API with ASP.NET Core

The tutorial did not work as expected. Since I work full-time with C# in our company, I stepped in to assist, but I noticed that the tutorial does not function correctly in its current state. Either the mention of Swagger needs to be removed, or the tutorial should be updated to reflect the necessary adjustments.

I found that only a few lines of code need modification to restore the expected functionality. I also came across issue #34558, which might be related, so I wanted to contribute a fix.

I hope this helps! Let me know if any further adjustments are needed.

Best regards,
Luke

[Added below by Wade Pickett]

Fixes #33001

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/tutorials/first-web-api.md	aspnetcore/tutorials/first-web-api

[lukekaese]

@dotnet-policy-service agree

[wadepickett]

@likekaese, thanks so much for your contribution, and I am sorry to hear of your colleague's experience.

This work for this was scheduled for this month's "sprint" and tracked in an issue here:
#33001

I wasn't going to hit this one until other work was completed this coming week, but I'll move it up since you are already starting, and I want you to be successful with the work you already put into it. Thanks very much for your start!

We usually try to keep code samples in a self-contained project directory for each version rather than putting the code inline to the .md doc itself. I already had a directory set up for that some time ago before I had to move over to higher priority work a while back here, but it wasn't updated yet:
https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/tutorials/first-web-api/samples

So next you will see the app samples replaced in code that included from the project samples.
We also had some guidance to add.

I will keep what I can of your work here so you get credit, but you will see some changes coming in soon (Today is Sunday and I might not be able to get a lot done until Monday).

Nothing for you to do at the moment as I am making those changes.

Thanks again for the contribution, greatly appreciated!

[lukekaese]

@wadepickett Thanks, I'm always happy to contribute! Good to know this was already planned, and I really appreciate you prioritizing it. Keeping code samples in separate project directories makes sense—I’ll keep that in mind for future contributions (and maybe some hobby projects). Looking forward to seeing how everything comes together. Let me know if there's anything else I can do. Thanks again!

[Rick-Anderson]

We're no longer using swagger. The .NET 9 controller API template generates the following code using the Swagger replacement, OpenAPI.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

[tdykstra]

We're no longer using swagger. The .NET 9 controller API template generates the following code using the Swagger replacement, OpenAPI.

Why was Swagger left in the tutorial, and this comment marked as resolved? I'm unresolving it so you can see my question.

Note that there are other instances of "Swashbuckle" "and "Swagger" that need to be addressed as well.

[wadepickett]

I resolved offline with Rick at the time, before setting as resolved here. The statement "We're no longer using swagger." was not correct as a broad statement. The Swashbuckle package tools are no longer used to generate the OpenAPI doc. Microsoft's OpenAPI package is now used for generating the OpenAPI doc. SwaggerUI is still used and recommended for generating UI for interactivity and uses that Microsoft created OpenAPI doc. See Safia's 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

[wadepickett]

@lukekaese, please don't make any changes or close. I'm in the middle of updating this PR with work I finished last night. I think there is some miscommunication around using SwaggerUI for visualization and interaction while OpenAPI generates the doc that SwaggerUI uses to provide visualization (What I am updating the PR for) vs using the Swashbuckle tools to generate the doc which, we would not do and the point I think Rick is raising. Sorting it out with Rick. Thanks.

[lukekaese]

@wadepickett I wasn't going to, but I was about to say something along those lines ^^. Perhaps my wording was a bit unclear, but yes, exactly as you said: OpenAPI is for generating, while SwaggerUI is for visualizing.

[wadepickett]

No worries, I understood.
Sorry for the delay and thanks for your patience. I will have a commit in here tonight further updating the doc, screenshots and app samples.

[wadepickett]

Moving as approved to new branch, then adding my changes in a moment...

[wadepickett]

Approving work so far so I can move this into a new branch and add changes from there.

[wadepickett]

Tab issue in doc, fixing it...

[wadepickett]

Close and reopening pr to flush cache.

[wadepickett]

@lukekaese please do not make any changes. Will let you know when it is in a state ready for review of my changes.

[wadepickett]

@tdykstra, I added a lot to this original PR for the update. It would be good to get a review from you since I added so much.
aspnetcore/tutorials/first-web-api

[tdykstra]

I reviewed and executed the instructions to validate them up to scaffolding the controller and skimmed the changes after that.

I thought we were going to use .http files for testing with VS in .NET 9 (?)

[tdykstra]

This is not rendering as a bulleted list.

[wadepickett]

Thanks for catching this. Trying to figure out what is wrong with it. It looks right in markdown.

[wadepickett]

@tdykstra, I cannot figure out why a blank line is showing up between the list items.

This for example, renders fine as a list:

The preceding highlighted code:

• Adds the Swagger UI as a service to the app with app.UseSwaggerUI().
• Sets the SwaggerEndpoint() option to the location of the OpenAPI documentation for this project.
• Ensures the Swagger UI is only available in the app development environment to limit information disclosure and security vulnerability.

This, which is set up the same way, throws in line spaces in the build, but does fine when displayed here:

This tutorial uses the following additional NuGet packages:

• Microsoft.EntityFrameworkCore.InMemory: Enables Entity Framework Core to work with an in-memory database rather than an external one, simplifying this tutorial.
• Swashbuckle.AspNetCore.SwaggerUI: Provides a user interface for exploring and testing API endpoints interactively through Swagger.

I can't spot what is tripping it up. I also checked against the style guide examples and other topics we have here doing the same thing. I tried removing the code ticks ` just in case there was some issue with that. That wasn't it either.

[tdykstra]

We're no longer using swagger. The .NET 9 controller API template generates the following code using the Swagger replacement, OpenAPI.

Why was Swagger left in the tutorial, and this comment marked as resolved? I'm unresolving it so you can see my question.

Note that there are other instances of "Swashbuckle" "and "Swagger" that need to be addressed as well.

[wadepickett]

I reviewed and executed the instructions to validate them up to scaffolding the controller and skimmed the changes after that.

I thought we were going to use .http files for testing with VS in .NET 9 (?)

@tdykstra, thanks.
This is the way and order Safia presented options here for .NET 9: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/using-openapi-documents?view=aspnetcore-9.0

• SwaggerUI (She installs it through the Swashbuckle.AspNetCore.SwaggerUi package )
• ReDocs
• Scalar
• Spectral

SwaggerUI is currently a heavily poplular tool out there for visualization/interactivity. We have examples in tutorials now using VS .http and Scalar, but I decided to maintain this one as the remaining SwaggerUI example. ( SwaggerUI using Microsofts OpenAPI package that creates the doc, which SwaggerUI uses to add the visualization. )

That seem good?

Also see my explanation on Swagger UI in the other comment above and that I had resolved with Rick offline before marking that item as resolved.

[wadepickett]

Sorry @lukekaese and @tdykstra, closing per #34746 (comment)

[wadepickett]

Reopening to get a build and will close back up.

[wadepickett]

Closing per note above.

[lukekaese]

@wadepickett don't worry. I'm sorry for wasting your time for a bit. At least the Documentation is getting better, That's all that counts. Maybe my next PR is more successful. Thanks you for everything ^^