Dela via

Använda openAPI-dokument

Använda Swagger-användargränssnittet för lokal ad hoc-testning

Som standard levereras inte Microsoft.AspNetCore.OpenApi-paketet med inbyggt stöd för visualisering eller interaktion med OpenAPI-dokumentet. Populära verktyg för att visualisera eller interagera med OpenAPI-dokumentet är Swagger UI och ReDoc. Swagger UI och ReDoc kan integreras i en app på flera sätt. Redigerare som Visual Studio och Visual Studio Code erbjuder tillägg och inbyggda funktioner för testning mot ett OpenAPI-dokument.

Swashbuckle.AspNetCore.SwaggerUi-paketet innehåller ett paket med Swagger-användargränssnittets webbtillgångar för användning i appar. Det här paketet kan användas för att återge ett användargränssnitt för det genererade dokumentet. Så här konfigurerar du detta:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Som bästa säkerhetsmetod för att begränsa avslöjande av information bör OpenAPI-användargränssnitt (Swagger UI, ReDoc, Scalar) endast aktiveras i utvecklingsmiljöer. Se till exempel Swagger OAuth 2.0-konfiguration.

Starta appen och gå till https://localhost:<port>/swagger för att visa Swagger-användargränssnittet.

För att automatiskt starta appen vid Swagger UI-URL:en genom att använda profilen https av Properties/launchSettings.json:

  • Bekräfta att launchBrowser är aktiverat (true).
  • Ange launchUrl till swagger.
"launchBrowser": true,
"launchUrl": "swagger",

Använda Scalar för interaktiv API-dokumentation

Scalar är ett interaktivt dokumentgränssnitt med öppen källkod för OpenAPI. Scalar kan integreras med OpenAPI-slutpunkten som tillhandahålls av ASP.NET Core. Installera Scalar.AspNetCore-paketet för att konfigurera Scalar.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapGet("/", () => "Hello world!");

app.Run();

Starta appen och gå till https://localhost:<port>/scalar för att visa scalar-användargränssnittet.

Så här startar du appen automatiskt på URL:en för Scalar UI med https-profilen av Properties/launchSettings.json.

  • Bekräfta att launchBrowser är aktiverat (true).
  • Ange launchUrl till scalar.
"launchBrowser": true,
"launchUrl": "scalar",

Lint-genererade OpenAPI-dokument med Spectral

Spectral är en OpenAPI-dokumentlinter med öppen källkod. Spectral kan införlivas i en appversion för att verifiera kvaliteten på genererade OpenAPI-dokument. Installera Spectral enligt installationsanvisningarna för -paketet.

Om du vill dra nytta av Spectral för att linting OpenAPI-dokument vid byggtillfället installerar Microsoft.Extensions.ApiDescription.Server du först paketet för att aktivera generering av OpenAPI-dokument för byggtid.

Aktivera dokumentgenerering vid byggtid genom att ange följande egenskaper i appens .csproj-fil":

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

Kör dotnet build för att generera dokumentet.

dotnet build

Skapa en .spectral.yml fil med följande innehåll.

extends: ["spectral:oas"]

Kör spectral lint på den genererade filen.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Stöd för injicering IOpenApiDocumentProvider

Du kan mata in IOpenApiDocumentProvider i dina tjänster via beroendeinmatning för att få åtkomst till OpenAPI-dokument programmatiskt, även utanför HTTP-begärandekontexter.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Registrera tjänsten i din DI-container:

builder.Services.AddScoped<DocumentService>();

Detta möjliggör scenarier som att generera klient-SDK:er, validera API-kontrakt i bakgrundsprocesser eller exportera dokument till externa system.

Stöd för injicering IOpenApiDocumentProvider introducerades i ASP.NET Core i .NET 10. Mer information finns i dotnet/aspnetcore #61463.

Information om hur du använder det genererade OpenAPI-dokumentet i ett minimalt API i .NET 6, 7 eller 8 finns i översikten över Swagger och NSwag.

Använda Swagger-användargränssnittet för lokal ad hoc-testning

Som standard levereras inte Microsoft.AspNetCore.OpenApi-paketet med inbyggt stöd för visualisering eller interaktion med OpenAPI-dokumentet. Populära verktyg för att visualisera eller interagera med OpenAPI-dokumentet är Swagger UI och ReDoc. Swagger UI och ReDoc kan integreras i en app på flera sätt. Redigerare som Visual Studio och VS Code erbjuder tillägg och inbyggda funktioner för testning mot ett OpenAPI-dokument.

Swashbuckle.AspNetCore.SwaggerUi-paketet innehåller ett paket med Swagger-användargränssnittets webbtillgångar för användning i appar. Det här paketet kan användas för att återge ett användargränssnitt för det genererade dokumentet. Så här konfigurerar du detta:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Som bästa säkerhetsmetod för att begränsa avslöjande av information bör OpenAPI-användargränssnitt (Swagger UI, ReDoc, Scalar) endast aktiveras i utvecklingsmiljöer. Se till exempel Swagger OAuth 2.0-konfiguration.

Starta appen och gå till https://localhost:<port>/swagger för att visa Swagger-användargränssnittet.

För att automatiskt starta appen vid Swagger UI-URL:en genom att använda profilen https av Properties/launchSettings.json:

  • Bekräfta att launchBrowser är aktiverat (true).
  • Ange launchUrl till swagger.
"launchBrowser": true,
"launchUrl": "swagger",

Använda Scalar för interaktiv API-dokumentation

Scalar är ett interaktivt dokumentgränssnitt med öppen källkod för OpenAPI. Scalar kan integreras med OpenAPI-slutpunkten som tillhandahålls av ASP.NET Core. Installera Scalar.AspNetCore-paketet för att konfigurera Scalar.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapGet("/", () => "Hello world!");

app.Run();

Starta appen och gå till https://localhost:<port>/scalar för att visa scalar-användargränssnittet.

Så här startar du appen automatiskt på URL:en för Scalar UI med https-profilen av Properties/launchSettings.json.

  • Bekräfta att launchBrowser är aktiverat (true).
  • Ange launchUrl till scalar.
"launchBrowser": true,
"launchUrl": "scalar",

Lint-genererade OpenAPI-dokument med Spectral

Spectral är en OpenAPI-dokumentlinter med öppen källkod. Spectral kan införlivas i en appversion för att verifiera kvaliteten på genererade OpenAPI-dokument. Installera Spectral enligt installationsanvisningarna för -paketet.

Om du vill dra nytta av Spectral installerar du Microsoft.Extensions.ApiDescription.Server-paketet för att aktivera OpenAPI-dokumentgenerering för byggtid.

Aktivera dokumentgenerering vid byggtid genom att ange följande egenskaper i appens .csproj-fil":

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

Kör dotnet build för att generera dokumentet.

dotnet build

Skapa en .spectral.yml fil med följande innehåll.

extends: ["spectral:oas"]

Kör spectral lint på den genererade filen.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)