Previous

Next

Exercise - Create a minimal API

Completed

You're a developer for a company, and you and your company have heard about the new minimal API. Your manager has asked you to create a project for it so that you can discuss whether to use it on your next project.

Note

This module uses the .NET CLI (Command Line Interface) and Visual Studio Code for local development. After completing this module, you can apply the concepts using Visual Studio (Windows), Visual Studio for Mac (macOS), or continued development using Visual Studio Code (Windows, Linux, & macOS).

This module uses the .NET 8.0 SDK. Ensure that you have .NET 8.0 installed by running the following command in your preferred command terminal:

dotnet --list-sdks

Output similar to the following example appears:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Ensure that a version that starts with 8 is listed. If none is listed or the command isn't found, install the most recent .NET 8.0 SDK.

Scaffold a project

First, you need to scaffold a project. You've installed .NET 8 and you're ready to go.

1. From a terminal, create a web API in a directory called PizzaStore by running dotnet new:

   dotnet new web -o PizzaStore -f net8.0
   

2. Switch to the new PizzaStore directory.

   cd PizzaStore
   

3. Run the app by calling dotnet run. It builds the app and hosts it on a port from 5000 to 5300. HTTPS has a port selected for it in the range of 7000 to 7300.

   Note

   If you want to override the random port selection behavior, you can set the ports to use in launchSettings.json.

   dotnet run
   

   Here's what the output can look like in the terminal:

   Building...
    info: Microsoft.Hosting.Lifetime[14]
          Now listening on: https://localhost:7200
    info: Microsoft.Hosting.Lifetime[14]
          Now listening on: http://localhost:5100
    info: Microsoft.Hosting.Lifetime[0]
          Application started. Press Ctrl+C to shut down.
    info: Microsoft.Hosting.Lifetime[0]
          Hosting environment: Development
    info: Microsoft.Hosting.Lifetime[0]
          Content root path: /<path>/PizzaStore
   

4. In your browser, go to the indicated port. According to the terminal http://localhost:{PORT}, you should see the text "Hello World!"

Congratulations! You've created an API by using a minimal API template.

Add Swagger

Use Swagger to ensure that you have a self-documenting API, where the docs change when you change the code.

1. Press Ctrl+C to stop running the API.

2. Install the Swashbuckle package:

   dotnet add package Swashbuckle.AspNetCore --version 6.5.0
   

3. Open the project in Visual Studio Code:

   code .
   

4. In Visual Studio Code, in the explorer pane, open PizzaStore.csproj. You should have an entry that looks like this one:

   <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
   

Next, configure your project to use Swagger.

1. Open Program.cs and add the highlighted code. Make sure you save your changes.

   using Microsoft.OpenApi.Models;
   
   var builder = WebApplication.CreateBuilder(args);
       
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen(c =>
   {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "PizzaStore API", Description = "Making the Pizzas you love", Version = "v1" });
   });
       
   var app = builder.Build();
       
   if (app.Environment.IsDevelopment())
   {
      app.UseSwagger();
      app.UseSwaggerUI(c =>
      {
         c.SwaggerEndpoint("/swagger/v1/swagger.json", "PizzaStore API V1");
      });
   }
       
   app.MapGet("/", () => "Hello World!");
       
   app.Run();
   

2. Press Ctrl+` to open a terminal in Code. In the new terminal, run the app again:

   dotnet run
   

3. Navigate to the app's swagger endpoint, http://localhost:{PORT}/swagger.

   You should see the following output:

   

4. In the terminal, press Ctrl+C to terminate the program.

You've successfully added OpenAPI support to your minimal API using Swagger!

Continue