ASP.NET Core web-API-documentatie met Swagger/OpenAPI

Door Rico Suter

Swagger (OpenAPI) is een taalagnostische specificatie voor het beschrijven van REST API's. Hiermee kunnen zowel computers als mensen inzicht krijgen in de mogelijkheden van een REST API zonder directe toegang tot de broncode. De belangrijkste doelstellingen zijn:

• Minimaliseer de hoeveelheid werk die nodig is om losgekoppelde services te verbinden.
• Verminder de hoeveelheid tijd die nodig is om een service nauwkeurig te documenteren.

De twee belangrijkste OpenAPI-implementaties voor .NET zijn Swashbuckle en NSwag, zie:

• Aan de slag met Swashbuckle
• Aan de slag met NSwag

OpenAPI versus Swagger

Het Swagger-project is in 2015 gedoneerd aan het OpenAPI-initiatief en wordt sindsdien OpenAPI genoemd. Beide namen worden door elkaar gebruikt. OpenAPI verwijst echter naar de specificatie. 'Swagger' verwijst naar de familie van opensource- en commerciële producten van SmartBear die werken met de OpenAPI-specificatie. Volgende opensource-producten, zoals OpenAPIGenerator, vallen ook onder de Swagger-familienaam, ondanks dat ze niet door SmartBear worden vrijgegeven.

Kortom:

• OpenAPI is een specificatie.
• Swagger is een hulpprogramma dat gebruikmaakt van de OpenAPI-specificatie. Bijvoorbeeld OpenAPIGenerator en SwaggerUI.

OpenAPI-specificatie (openapi.json)

De OpenAPI-specificatie is een document waarin de mogelijkheden van uw API worden beschreven. Het document is gebaseerd op de XML- en kenmerkaantekeningen binnen de controllers en modellen. Het is het kernonderdeel van de OpenAPI-stroom en wordt gebruikt om hulpprogramma's zoals SwaggerUI aan te sturen. Standaard heeft deze de naam openapi.json. Hier volgt een voorbeeld van een OpenAPI-specificatie, verminderd voor beknoptheid:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

Swagger UI biedt een webgebruikersinterface die informatie over de service biedt met behulp van de gegenereerde OpenAPI-specificatie. Zowel Swashbuckle als NSwag bevatten een ingesloten versie van de Swagger-gebruikersinterface, zodat deze kan worden gehost in uw ASP.NET Core-app met behulp van een middleware-registratieaanroep. De webgebruikersinterface ziet er als volgt uit:

Elke openbare actiemethode in uw controllers kan worden getest vanuit de gebruikersinterface. Selecteer een methodenaam om de sectie uit te vouwen. Voeg eventueel benodigde parameters toe en selecteer Uitproberen!.

Opmerking

De Swagger UI-versie die wordt gebruikt voor de schermopnamen is versie 2. Zie Petstore-voorbeeld voor een voorbeeld van versie 3.

Swagger UI-eindpunten beveiligen

Aanroep MapSwagger().RequireAuthorization om de Swagger UI-eindpunten te beveiligen. In het volgende voorbeeld worden de swagger-eindpunten beveiligd:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

In de voorgaande code heeft het /weatherforecast eindpunt geen autorisatie nodig, maar de Swagger-eindpunten wel.

De volgende Curl geeft een JWT-token door om het Swagger UI-eindpunt te testen:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Zie Tokens genereren met dotnet user-jwts voor meer informatie over testen met JWT-tokens.

Genereer een XML-documentatiebestand tijdens het compileren.

Zie GenerateDocumentationFile voor meer informatie.

Volgende stappen

• Aan de slag met Swashbuckle
• Aan de slag met NSwag