Dokumentacja internetowego interfejsu API platformy ASP.NET Core ze strukturą Swagger/interfejsem OpenAPI

Autor : Christoph Nienaber i Rico Suter

Swagger (OpenAPI) to niezależna od języka specyfikacja do opisywania REST interfejsów API. Umożliwia ona zarówno komputerom, jak i ludziom zrozumienie możliwości interfejsu REST API bez bezpośredniego dostępu do kodu źródłowego. Jego głównymi celami są:

• Zminimalizuj ilość pracy potrzebnej do połączenia usług rozdzielonych.
• Zmniejsz ilość czasu potrzebnego do dokładnego udokumentowania usługi.

Dwie główne implementacje interfejsu OpenAPI dla platformy .NET to Swashbuckle i NSwag, zobacz:

• Wprowadzenie do programu Swashbuckle
• Wprowadzenie do sieciowej grupy zabezpieczeń

OpenAPI a Swagger

Projekt struktury Swagger został przekazany do inicjatywy OpenAPI w 2015 r. i od tego czasu jest określany jako OpenAPI. Obie nazwy są używane zamiennie. Jednak "OpenAPI" odnosi się do specyfikacji. "Swagger" odnosi się do rodziny produktów typu open source i komercyjnych firmy SmartBear, które współpracują ze specyfikacją OpenAPI. Kolejne produkty open source, takie jak OpenAPIGenerator, również należą do nazwy rodziny Swagger, mimo że nie są wydawane przez SmartBear.

Krótko mówiąc:

• Interfejs OpenAPI jest specyfikacją.
• Swagger to narzędzia korzystające ze specyfikacji interfejsu OpenAPI. Na przykład OpenAPIGenerator i SwaggerUI.

Specyfikacja interfejsu OpenAPI (openapi.json)

Specyfikacja interfejsu OpenAPI to dokument opisujący możliwości interfejsu API. Dokument jest oparty na adnotacjach XML i atrybutów w kontrolerach i modelach. Jest to podstawowa część przepływu OpenAPI i służy do napędzania narzędzi, takich jak SwaggerUI. Domyślnie ma ona nazwę openapi.json. Oto przykład specyfikacji interfejsu OpenAPI zredukowanej do zwięzłości:

{
  "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
      }
    }
  }
}

Interfejs użytkownika struktury Swagger

Interfejs użytkownika struktury Swagger oferuje internetowy interfejs użytkownika, który udostępnia informacje o usłudze przy użyciu wygenerowanej specyfikacji interfejsu OpenAPI. Zarówno pakiet Swashbuckle, jak i NSwag zawierają osadzoną wersję interfejsu użytkownika struktury Swagger, dzięki czemu może być hostowana w aplikacji ASP.NET Core przy użyciu wywołania rejestracji oprogramowania pośredniczącego. Internetowy interfejs użytkownika wygląda następująco:

Każda metoda akcji publicznej w kontrolerach może być testowana z poziomu interfejsu użytkownika. Wybierz nazwę metody, aby rozwinąć sekcję. Dodaj wszelkie niezbędne parametry i wybierz pozycję Wypróbuj!.

Uwaga

Wersja interfejsu użytkownika struktury Swagger używana na potrzeby zrzutów ekranu to wersja 2. Aby zapoznać się z przykładem wersji 3, zobacz Przykład magazynu petstore.

Zabezpieczanie punktów końcowych interfejsu użytkownika programu Swagger

Wywołaj metodę MapSwagger().RequireAuthorization w celu zabezpieczenia punktów końcowych interfejsu użytkownika programu Swagger. Poniższy przykład zabezpiecza punkty końcowe struktury 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);
}

W poprzednim kodzie /weatherforecast punkt końcowy nie potrzebuje autoryzacji, ale punkty końcowe programu Swagger działają.

Poniższy program Curl przekazuje token JWT w celu przetestowania punktu końcowego interfejsu użytkownika struktury Swagger:

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

Aby uzyskać więcej informacji na temat testowania za pomocą tokenów JWT, zobacz Generowanie tokenów za pomocą biblioteki dotnet user-jwts.

Generowanie pliku dokumentacji XML w czasie kompilacji.

Aby uzyskać więcej informacji, zobacz GenerateDocumentationFile .

Następne kroki

• Wprowadzenie do pakietu Swashbuckle
• Wprowadzenie do łańcucha narzędzi NSwag