Podpora OpenAPI v aplikacích rozhraní API pro ASP.NET Core

ASP.NET Core podporuje generování dokumentů OpenAPI v aplikacích založených na kontroleru a minimálních rozhraníCH API. Specifikace OpenAPI je programovací standard nezávislý na jazyce pro dokumentaci rozhraní HTTP API. Tento standard se podporuje v aplikacích ASP.NET Core prostřednictvím kombinace integrovaných rozhraní API a opensourcových knihoven. Integrace OpenAPI v aplikaci má tři klíčové aspekty:

• Generování informací okoncovýchch
• Shromažďování informací do formátu, který odpovídá schématu OpenAPI.
• Vystavení vygenerovaného dokumentu OpenAPI prostřednictvím vizuálního uživatelského rozhraní nebo serializovaného souboru

aplikace ASP.NET Core poskytují integrovanou podporu generování informací o koncových bodech v aplikaci prostřednictvím Microsoft.AspNetCore.OpenApi balíčku.

Následující kód vygeneruje ASP.NET minimální šablona webového rozhraní API a používá 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);
}

V předchozím zvýrazněném kódu:

• AddOpenApi registruje služby potřebné pro generování dokumentů OpenAPI do kontejneru DI aplikace.
• MapOpenApi přidá do aplikace koncový bod pro zobrazení dokumentu OpenAPI serializovaného do formátu JSON. Koncový bod OpenAPI je omezený na vývojové prostředí, aby se minimalizovalo riziko vystavení citlivých informací a snížení ohrožení zabezpečení v produkčním prostředí.

Microsoft.AspNetCore.OpenApi Balíček NuGet

Balíček Microsoft.AspNetCore.OpenApi obsahuje následující funkce:

• Podpora generování dokumentů OpenAPI za běhu a přístup k nim prostřednictvím koncového bodu v aplikaci
• Podpora rozhraní API transformátoru, která umožňují upravovat vygenerovaný dokument.

Pokud chcete balíček použít Microsoft.AspNetCore.OpenApi , přidejte ho jako PackageReference do souboru 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>

Další informace o Microsoft.AspNetCore.OpenApi balíčku najdete v tématu Generování dokumentů OpenAPI.

Microsoft.Extensions.ApiDescription.Server Balíček NuGet

Balíček Microsoft.Extensions.ApiDescription.Server poskytuje podporu pro generování dokumentů OpenAPI v době sestavení a jejich serializaci.

Pokud ho chcete použít Microsoft.Extensions.ApiDescription.Server, přidejte ho jako PackageReference do souboru projektu. Generování dokumentů v době sestavení je povoleno nastavením OpenApiGenerateDocuments vlastnosti. Ve výchozím nastavení se vygenerovaný dokument OpenAPI uloží do obj adresáře, ale výstupní adresář můžete přizpůsobit nastavením OpenApiDocumentsDirectory vlastnosti.

<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>

Rozhraní API v. Operace rozhraní API v. Koncový bod rozhraní API

Následující části popisují rozdíly mezi rozhraním API, koncovým bodem rozhraní API a operací rozhraní API v kontextu dokumentace k ASP.NET Core a OpenAPI.

ROZHRANÍ API (aplikační programovací rozhraní)

Rozhraní API je sada zásad a protokolů pro vytváření a interakci se softwarovými aplikacemi. Definuje, jak mají různé softwarové komponenty komunikovat. Obecně vývoj webu "API" obvykle odkazuje na webovou službu, která zpřístupňuje funkce prostřednictvím protokolu HTTP.

V ASP.NET Core se rozhraní API obvykle sestavuje pomocí kontrolerů nebo minimálních rozhraní API, která zpracovávají příchozí požadavky HTTP a vracejí odpovědi.

Interní zásady pojmenování v ASP.NET Core někdy používají "rozhraní API" odlišně. Například v Průzkumníku rozhraní API představuje "ApiDescription" operaci rozhraní API místo úplné služby API. Tento rozdíl odráží interní konvence pojmenování a někdy se liší od širší definice, která se zde používá.

Další informace o Průzkumníku rozhraní API najdete v tématu Úvod k rozhraní APIExplorer v ASP.NET Core .

Operace rozhraní API

Operace rozhraní API představuje konkrétní akci nebo funkci, kterou poskytuje rozhraní API. V ASP.NET Core to odpovídá:

• Metody akcí kontroleru v rozhraních API ve stylu MVC
• Obslužné funkce tras v minimalním API

Každá operace je definována metodou HTTP (GET, POST, PUT, atd.), cestou, parametry a odpověďmi.

Koncový bod rozhraní API

Koncový bod rozhraní API je konkrétní adresa URL:

• Představuje konkrétní prostředek nebo funkce vystavené rozhraním API.
• Poskytuje přesnou adresu, na kterou klient potřebuje odeslat požadavek HTTP, aby mohl komunikovat s konkrétní operací rozhraní API.

Koncový bod je kombinace základní adresy URL rozhraní API a konkrétní cesty k požadovanému prostředku spolu s podporovanými metodami HTTP:

• U rozhraní API založených na kontroleru kombinují koncové body šablonu trasy s kontrolerem a akcí.
• U minimálních rozhraní API jsou koncové body explicitně definovány pomocí app.MapGet()app.MapPost()atd.

Například api/products/{id} koncový bod, který podporuje následující operace:

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

Koncové body často zahrnují parametry dotazu, například GET /api/products?category=electronics&sort=price

Dokumentace k OpenAPI

V kontextu OpenAPI popisuje dokumentace rozhraní API jako celek, včetně všech jeho koncových bodů a operací. OpenAPI poskytuje strukturovaný způsob, jak dokumentovat rozhraní API, což vývojářům usnadňuje pochopení toho, jak s nimi pracovat.

Operace rozhraní API jsou primárním cílem dokumentace OpenAPI. Specifikace OpenAPI organizuje dokumentaci podle operací, které jsou seskupené podle cest (koncových bodů). Každá operace je popsána s podrobnostmi, jako jsou parametry, těla požadavků, odpovědi a další. Tento strukturovaný formát umožňuje nástrojům automaticky generovat klientské knihovny, zástupné procedury serveru a interaktivní dokumentaci.

V dokumentu OpenAPI:

• Celý dokument popisuje rozhraní API jako celek.
• Každá položka cesty (například /api/products/{id}) představuje koncový bod.
• V každé cestě definují metody HTTP (GET, POST, PUTatd.) operace.
• Každá operace obsahuje podrobnosti o parametrech, textu požadavku, odpovědích atd.

Příklad ve formátu JSON OpenAPI:

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

Porovnání rozhraní API, operace rozhraní API a koncového bodu rozhraní API

Následující tabulka shrnuje rozdíly mezi rozhraním API, operací rozhraní API a koncovým bodem rozhraní API:

Koncepce	Operace rozhraní API	Koncový bod rozhraní API
definice	Logický popis akce rozhraní API: metoda + cesta + chování	Skutečná nakonfigurovaná trasa HTTP, která naslouchá požadavkům
Úroveň	Koncepčně, jaká akce se může stát?	Jaká konkrétní adresa URL a metoda se shodují?
Svázaný s	Návrh a specifikace rozhraní Api OpenAPI	směrování ASP.NET Core za běhu
Popisuje	Co rozhraní API dělá, například „vytvořit produkt“	Kde a jak ho volat, například POST https://localhost:7099/api/products, POST https://contoso.com/api/products
V ASP.NET Core	Akce kontroleru nebo metody Minimal API před vyřešením směrování	Objekty koncového bodu vyřešené během běhu

ASP.NET základní zdrojový kód OpenAPI na GitHubu

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Další materiály

• Ověřování a autorizace v minimálních rozhraních API