Usar documentos openAPI

Usar a interface Swagger para testes locais ad-hoc

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

O pacote Swashbuckle.AspNetCore.SwaggerUi fornece um conjunto de recursos web do Swagger UI para utilização em aplicações. Este 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 anteriormente registrada.

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 uma prática recomendada de segurança para limitar a divulgação de informações, as interfaces de usuário OpenAPI (Swagger UI, ReDoc, Scalar) só devem ser habilitadas em ambientes de desenvolvimento. Por exemplo, consulte Configuração do Swagger OAuth 2.0.

Inicie a aplicação e navegue até https://localhost:<port>/swagger para exibir a interface do utilizador do Swagger.

Para iniciar automaticamente a aplicação na URL do Swagger UI usando o perfil https de Properties/launchSettings.json:

• Confirme se launchBrowser está ativado (true).
• Defina o launchUrl como swagger.

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

Usar o Scalar para documentação interativa da API

Scalar é uma interface de usuário de documento interativo de código aberto para OpenAPI. O Scalar pode ser integrado 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 a aplicação e navegue até https://localhost:<port>/scalar para visualizar a Interface Scalar do utilizador.

Para iniciar automaticamente a aplicação no URL da interface de utilizador do Scalar, utilizando o perfil https de Properties/launchSettings.json:

• Confirme se launchBrowser está ativado (true).
• Defina o launchUrl como scalar.

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

Lint gerou documentos OpenAPI com Spectral

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

Para aproveitar o Spectral para alinhar documentos OpenAPI em tempo de compilação, primeiro instale o pacote para habilitar a Microsoft.Extensions.ApiDescription.Server geração de documentos OpenAPI em tempo de compilação.

Habilite a geração de documentos em 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 seguinte conteúdo.

extends: ["spectral:oas"]

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 de 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");
    }
}

Registe o serviço no seu contentor DI:

builder.Services.AddScoped<DocumentService>();

Isso permite cenários como a geração de SDKs de cliente, a validação de contratos de API em processos em segundo plano ou a exportação de 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.