Obsługa interfejsu OpenAPI w aplikacjach interfejsu API platformy ASP.NET Core

ASP.NET Core obsługuje generowanie dokumentów OpenAPI w aplikacjach opartych na kontrolerach i minimalnych interfejsach API. Specyfikacja interfejsu OpenAPI to niezależny od języka programowania standard do dokumentowania interfejsów API PROTOKOŁU HTTP. Ten standard jest obsługiwany w aplikacjach ASP.NET Core za pomocą kombinacji wbudowanych interfejsów API i bibliotek open source. W aplikacji istnieją trzy kluczowe aspekty integracji interfejsu OpenAPI:

• Generowanie informacji o punktach końcowych w aplikacji.
• Zbieranie informacji w formacie zgodnym ze schematem OpenAPI.
• Uwidacznianie wygenerowanego dokumentu OpenAPI za pomocą wizualnego interfejsu użytkownika lub serializowanego pliku.

aplikacje ASP.NET Core zapewniają wbudowaną obsługę generowania informacji o punktach końcowych w aplikacji za pośrednictwem Microsoft.AspNetCore.OpenApi pakietu.

Poniższy kod jest generowany przez szablon interfejsu API internetowego ASP.NET Core i używa interfejsu OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

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

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

app.Run();

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

W poprzednim wyróżnionym kodzie:

• AddOpenApi rejestruje usługi wymagane do generowania dokumentów OpenAPI w kontenerze DI aplikacji.
• MapOpenApi dodaje punkt końcowy do aplikacji do wyświetlania dokumentu OpenAPI serializowanego w formacie JSON. Punkt końcowy interfejsu OpenAPI jest ograniczony do środowiska programistycznego, aby zminimalizować ryzyko ujawnienia poufnych informacji i zmniejszyć luki w zabezpieczeniach w środowisku produkcyjnym.

Microsoft.AspNetCore.OpenApi Pakiet NuGet

Pakiet Microsoft.AspNetCore.OpenApi udostępnia następujące funkcje:

• Obsługa generowania dokumentów OpenAPI w czasie wykonywania i uzyskiwania do nich dostępu za pośrednictwem punktu końcowego w aplikacji.
• Obsługa interfejsów API przekształcania, które umożliwiają modyfikowanie wygenerowanego dokumentu.

Aby użyć Microsoft.AspNetCore.OpenApi pakietu, dodaj go jako packageReference do pliku projektu:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Aby dowiedzieć się więcej o pakiecie Microsoft.AspNetCore.OpenApi , zobacz Generowanie dokumentów OpenAPI.

Microsoft.Extensions.ApiDescription.Server Pakiet NuGet

Pakiet Microsoft.Extensions.ApiDescription.Server zapewnia obsługę generowania dokumentów OpenAPI w czasie kompilacji i ich serializacji.

Aby użyć Microsoft.Extensions.ApiDescription.Serverpolecenia , dodaj go jako element PackageReference do pliku projektu. Generowanie dokumentów w czasie kompilacji jest włączone przez ustawienie OpenApiGenerateDocuments właściwości . Domyślnie wygenerowany dokument OpenAPI jest zapisywany w obj katalogu, ale można dostosować katalog wyjściowy, ustawiając OpenApiDocumentsDirectory właściwość .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Interfejs API v. Operacja interfejsu API (v.) Punkt końcowy interfejsu API

W poniższych sekcjach opisano różnice między interfejsem API, punktem końcowym interfejsu API i operacją interfejsu API w kontekście dokumentacji ASP.NET Core i OpenAPI.

Interfejs programowania aplikacji (API)

Interfejs API to zestaw reguł i protokołów do tworzenia i interakcji z aplikacjami oprogramowania. Definiuje sposób komunikowania się różnych składników oprogramowania. Ogólnie rzecz biorąc, "API" zwykle odnosi się do usługi internetowej, która udostępnia funkcjonalność przez HTTP.

W ASP.NET Core interfejs API jest zwykle kompilowany przy użyciu kontrolerów lub minimalnych interfejsów API, które obsługują przychodzące żądania HTTP i zwracane odpowiedzi.

Czasami wewnętrzne konwencje nazewnictwa ASP.NET Core używają "API" inaczej. Na przykład w Eksploratorze interfejsów API "ApiDescription" faktycznie reprezentuje operację interfejsu API , a nie pełną usługę interfejsu API. To rozróżnienie odzwierciedla wewnętrzne konwencje nazewnictwa, a czasami różni się od szerszej definicji użytej tutaj.

Aby uzyskać więcej informacji na temat Eksploratora interfejsów API, zobacz Wprowadzenie do interfejsu APIExplorer w programie ASP.NET Core .

Operacja interfejsu API

Operacja interfejsu API reprezentuje określoną akcję lub możliwość zapewnianą przez interfejs API. W ASP.NET Core odpowiada to:

• Metody akcji kontrolera w interfejsach API w stylu MVC
• Obsługiwacze tras w minimalnych API

Każda operacja jest definiowana przez metodę HTTP (GET, POST, PUTitp.), ścieżkę, parametry i odpowiedzi.

Punkt końcowy interfejsu API

Punkt końcowy interfejsu API to określony adres URL:

• Reprezentuje określony zasób lub funkcje uwidocznione przez interfejs API.
• Zawiera dokładny adres, do którego klient musi wysłać żądanie HTTP w celu interakcji z określoną operacją interfejsu API.

Punkt końcowy to kombinacja podstawowego adresu URL interfejsu API i określonej ścieżki do żądanego zasobu wraz z obsługiwanymi metodami HTTP:

• W przypadku interfejsów API opartych na kontrolerach punkty końcowe łączą szablon trasy z kontrolerem i akcją.
• W przypadku Minimal APIs punkty końcowe są jawnie zdefiniowane za pomocą app.MapGet(), app.MapPost() itp.

Na przykład api/products/{id} punkt końcowy obsługujący następujące operacje:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Punkty końcowe często zawierają parametry zapytania, na przykład GET /api/products?category=electronics&sort=price

Dokumentacja interfejsu OpenAPI

W kontekście interfejsu OpenAPI w dokumentacji opisano cały interfejs API, w tym wszystkie jego punkty końcowe i operacje. OpenAPI zapewnia ustrukturyzowany sposób dokumentowania interfejsów API, co ułatwia deweloperom zrozumienie, jak się z nimi komunikować.

Operacje interfejsu API są głównym celem dokumentacji interfejsu OpenAPI. Specyfikacja interfejsu OpenAPI organizuje dokumentację według operacji, które są pogrupowane według ścieżek (punktów końcowych). Każda operacja jest opisana ze szczegółami, takimi jak parametry, treść żądania, odpowiedzi i inne. Ten format ustrukturyzowany umożliwia automatyczne generowanie bibliotek klienckich, wycinków serwera i interaktywnej dokumentacji.

W dokumencie OpenAPI:

• Cały dokument opisuje interfejs API jako całość
• Każdy element ścieżki (na przykład /api/products/{id}) reprezentuje punkt końcowy
• W każdej ścieżce metody HTTP (GET, POST, PUTitp.) definiują operacje
• Każda operacja zawiera szczegółowe informacje o parametrach, treści żądania, odpowiedziach itp.

Przykład w formacie OpenAPI JSON:

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

Porównanie interfejsów API, operacji interfejsu API i punktu końcowego interfejsu API

W poniższej tabeli przedstawiono podsumowanie różnic między interfejsem API, operacją interfejsu API i punktem końcowym interfejsu API:

Pojęcie	Operacja interfejsu API	Punkt końcowy interfejsu API
Definicja	Logiczny opis akcji interfejsu API: metoda + ścieżka i zachowanie	Rzeczywista skonfigurowana trasa HTTP, która nasłuchuje żądań
Poziom	Jakie działania mogą teoretycznie wystąpić	Konkretny, jaki adres URL i metoda są dopasowane
Powiązane z	Specyfikacja interfejsu API OpenAPI	Trasowanie ASP.NET Core w czasie wykonywania
Opisuje	Co robi API, na przykład "utwórz produkt"	Gdzie i jak go wywołać, na przykład , POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
W ASP.NET Core	Akcje kontrolera lub minimalne metody interfejsu API, zanim nastąpi rozwiązanie routingu	Obiekty punktu końcowego rozstrzygnięte w czasie wykonania

kod źródłowy interfejsu OpenAPI platformy ASP.NET Core w witrynie GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Dodatkowe zasoby

• Uwierzytelnianie i autoryzacja w minimalnych interfejsach API