Usar documentos OpenAPI

Usar a interface Swagger para testes ad hoc locais

Por padrão, o pacote Microsoft.AspNetCore.OpenApi não é fornecido com suporte interno para visualizar ou interagir com o documento OpenAPI. Ferramentas populares para visualizar ou interagir com o documento OpenAPI incluem a interface do usuário do Swagger e o ReDoc. A interface do usuário do Swagger e o ReDoc podem ser integrados em um aplicativo de várias maneiras. Editores como o Visual Studio e o Visual Studio Code oferecem extensões e experiências internas para teste em um documento OpenAPI.

O pacote Swashbuckle.AspNetCore.SwaggerUi fornece um pacote de ativos da Web da interface do usuário do Swagger para uso em aplicativos. Esse pacote pode ser usado para renderizar uma interface do usuário para o documento gerado. Para configurar isso:

• Instale o pacote Swashbuckle.AspNetCore.SwaggerUi.
• Habilite o middleware swagger-ui com uma referência à rota OpenAPI registrada anteriormente.

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

Como prática recomendada de segurança para limitar a divulgação de informações, as interfaces de usuário do OpenAPI (interface do usuário do Swagger, ReDoc, Scalar) só devem ser habilitadas em ambientes de desenvolvimento. Por exemplo, consulte a configuração do Swagger OAuth 2.0.

Inicie o aplicativo e navegue até https://localhost:<port>/swagger para visualizar a interface do usuário do Swagger.

Para iniciar automaticamente o aplicativo na URL da interface do usuário do Swagger usando o perfil de https de Properties/launchSettings.json:

• Confirme se launchBrowser está habilitado (true).
• Defina o launchUrl para swagger.

"launchBrowser": true,
"launchUrl": "swagger",

Usar Escalar para documentação de API interativa

Escalar é uma UI de documento interativo de código aberto para OpenAPI. Scalar pode integrar com o endpoint OpenAPI fornecido pelo ASP.NET Core. Para configurar o Scalar, instale o pacote Scalar.AspNetCore.

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

Inicie o aplicativo e navegue até https://localhost:<port>/scalar para exibir a Scalar UI.

Para iniciar automaticamente o aplicativo na URL da interface do usuário do Scalar usando o perfil do https de Properties/launchSettings.json:

• Confirme se launchBrowser está habilitado (true).
• Defina o launchUrl para scalar.

"launchBrowser": true,
"launchUrl": "scalar",

Executar lint de documentos OpenAPI gerados com Spectral

Spectral é um linter de documento OpenAPI de código aberto. O Spectral pode ser incorporado ao build do aplicativo para verificar a qualidade dos documentos OpenAPI gerados. Instale o Spectral de acordo com as instruções de instalação do pacote.

Para utilizar o Spectral para a análise de documentos OpenAPI durante a fase de compilação, primeiro instale o pacote Microsoft.Extensions.ApiDescription.Server para habilitar a geração de documentos OpenAPI nessa etapa.

Habilite a geração de documentos no tempo de compilação definindo as seguintes propriedades no arquivo .csproj do aplicativo":

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

Execute dotnet build para gerar o documento.

dotnet build

Crie um arquivo .spectral.yml com o conteúdo a seguir.

extends: ["spectral:oas"]

Depois, execute spectral lint no arquivo gerado.

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)

Suporte para injeção IOpenApiDocumentProvider

Você pode injetar IOpenApiDocumentProvider em seus serviços por meio da injeção de dependência para acessar documentos OpenAPI programaticamente, mesmo fora dos contextos de solicitação HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

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

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

Registre o serviço em seu contêiner de DI:

builder.Services.AddScoped<DocumentService>();

Isso permite cenários como gerar SDKs de cliente, validar contratos de API em processos em segundo plano ou exportar documentos para sistemas externos.

O suporte para injeção IOpenApiDocumentProvider foi introduzido no ASP.NET Core no .NET 10. Para obter mais informações, consulte dotnet/aspnetcore #61463.