Dokumentace k webovému rozhraní API ASP.NET Core s využitím Swaggeru/OpenAPI

Autor: Rico Suter

Tento článek popisuje použití nástrojů Swaggeru poskytované balíčky Swashbuckle.AspNetCore a NSwag k vygenerování dokumentace OpenAPI a interaktivních stránek nápovědy pro webová rozhraní API pro ASP.NET Core.

V .NET 9 a novějších obsahuje ASP.NET Core integrovanou podporu OpenAPI, která nahrazuje Swashbuckle jako výchozí. Swashbuckle už není součástí šablon projektů, ale zůstane k dispozici jako komunitní balíček, který můžete přidat ručně.

• Informace o integrovaných funkcích OpenAPI najdete v přehledu podpory OpenAPI v aplikacích ASP.NET Core API.
• Pokud chcete přidat uživatelské rozhraní Swagger pro interaktivní zkoumání nebo místní ad hoc testování společně s integrovanou podporou OpenAPI, přečtěte si téma Použití vygenerovaných dokumentů OpenAPI.

Následující pokyny platí pro projekty používající Swashbuckle nebo NSwag s ASP.NET Core 8.0 a starší.

Swagger (OpenAPI) je specifikace nezávislá na jazyce pro popis REST rozhraní API. Umožňuje počítačům i lidem pochopit možnosti REST rozhraní API bez přímého přístupu ke zdrojovému kódu. Jeho hlavními cíli jsou:

• Minimalizujte množství práce potřebné k propojení oddělených služeb.
• Zkraťte dobu potřebnou k přesnému zdokumentování služby.

Dvě hlavní implementace OpenAPI pro .NET jsou Swashbuckle a NSwag, viz:

• Začínáme s Swashbuckle
• Začínáme se službou NSwag

OpenAPI vs. Swagger

Projekt Swagger byl darován iniciativě OpenAPI v roce 2015 a od té doby se označuje jako OpenAPI. Oba názvy se používají zaměnitelně. OpenAPI ale odkazuje na specifikaci. "Swagger" odkazuje na řadu opensourcových a komerčních produktů z SmartBear, které pracují se specifikací OpenAPI. Další open-sourceové produkty, jako OpenAPIGenerator, také spadají do rodiny Swagger, i když nebyly vydány společností SmartBear.

Zkrátka:

• OpenAPI je specifikace.
• Swagger je nástroje, které používají specifikaci OpenAPI. Například OpenAPIGenerator a SwaggerUI.

Specifikace OpenAPI (openapi.json)

Specifikace OpenAPI je dokument, který popisuje možnosti vašeho rozhraní API. Dokument je založený na anotách XML a atributů v rámci kontrolerů a modelů. Je to základní část toku OpenAPI a slouží k řízení nástrojů, jako je SwaggerUI. Ve výchozím nastavení se jmenuje openapi.json. Tady je příklad specifikace OpenAPI, která se zmenší pro stručnost:

{
  "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 nabízí webové uživatelské rozhraní , které poskytuje informace o službě pomocí vygenerované specifikace OpenAPI. Swashbuckle i NSwag zahrnují vloženou verzi uživatelského rozhraní Swaggeru, aby ji bylo možné hostovat ve vaší aplikaci ASP.NET Core pomocí volání registrace middlewaru. Webové uživatelské rozhraní vypadá takto:

Jednotlivé metody veřejné akce v kontrolerů je možné testovat z uživatelského rozhraní. Výběrem názvu metody rozbalte oddíl. Přidejte všechny potřebné parametry a vyberte Vyzkoušet!.

Poznámka:

Verze uživatelského rozhraní Swaggeru používaná pro snímky obrazovky je verze 2. Příklad verze 3 najdete v příkladu Petstore.

Zabezpečení koncových bodů uživatelského rozhraní Swagger

Zavolejte MapSwagger().RequireAuthorization pro zabezpečení koncových bodů Swagger UI. Následující příklad zabezpečuje koncové body Swagger:

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);
}

V předchozím kódu nepotřebuje koncový bod /weatherforecast autorizaci, ale koncové body Swaggeru ji potřebují.

Následující curl předá token JWT k otestování koncového bodu uživatelského rozhraní Swagger:

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

{TOKEN} kde zástupný symbol je nosný token JWT a {PORT} zástupný symbol je číslo portu.

Další informace o testování pomocí tokenů JWT najdete v tématu Generování tokenů pomocí dotnet user-jwts.

Generování souboru dokumentace XML v době kompilace

Další informace najdete v souboru GenerateDocumentationFile .

Další kroky

• Začínáme se službou Swashbuckle
• Začínáme se službou NSwag