Gerar documentos OpenAPI

O pacote Microsoft.AspNetCore.OpenApi fornece suporte interno para a geração de documentos OpenAPI no ASP.NET Core. O pacote fornece os seguintes recursos:

• Suporte para geração de documentos OpenAPI em tempo de execução e acesso a esses documentos por meio de um ponto de extremidade no aplicativo.
• Suporte para APIs "transformadoras" que permitem modificar o documento gerado.
• Suporte para gerar vários documentos OpenAPI a partir de um único aplicativo.
• Aproveita o suporte ao esquema JSON fornecido por System.Text.Json.
• É compatível com o AoT nativo.

Instalação do pacote

Instalar o pacote Microsoft.AspNetCore.OpenApi:

Visual Studio

Execute o seguinte comando no Console do Gerenciador de Pacotes:

Install-Package Microsoft.AspNetCore.OpenApi

CLI do .NET

Execute o comando a seguir:

dotnet add package Microsoft.AspNetCore.OpenApi

Configurar a geração de documentos OpenAPI

O seguinte código:

• Adiciona serviços OpenAPI.
• Habilita o ponto de extremidade para exibir o documento OpenAPI no formato JSON.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Inicie o aplicativo e navegue até https://localhost:<port>/openapi/v1.json para exibir o documento OpenAPI gerado.

Opções para personalizar a geração de documentos OpenAPI

As seções a seguir demonstram como personalizar a geração de documentos OpenAPI.

Personalizar o nome do documento OpenAPI

Cada documento OpenAPI em um aplicativo tem um nome exclusivo. O nome do documento padrão registrado é v1.

builder.Services.AddOpenApi(); // Document name is v1

Para modificar o nome do documento, passe o nome como um parâmetro para a chamada AddOpenApi.

builder.Services.AddOpenApi("internal"); // Document name is internal

O nome do documento aparece em vários locais na implementação do OpenAPI.

Ao buscar o documento OpenAPI gerado, o nome do documento é fornecido como o argumento de parâmetro documentName na solicitação. As solicitações a seguir resolvem os documentos v1 e internal.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Personalizar a versão do OpenAPI de um documento gerado

Por padrão, a geração de documentos OpenAPI cria um documento compatível com a v3.0 da especificação OpenAPI. O código a seguir demonstra como modificar a versão padrão do documento OpenAPI:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

Personalizar a rota do ponto de extremidade OpenAPI

Por padrão, o ponto de extremidade OpenAPI registrado por meio de uma chamada para MapOpenApi expõe o documento no ponto de extremidade /openapi/{documentName}.json. O código a seguir demonstra como personalizar a rota na qual o documento OpenAPI está registrado:

app.MapOpenApi("/openapi/{documentName}/openapi.json");

É possível, mas não recomendado, remover o parâmetro de rota documentName da rota do ponto de extremidade. Quando o parâmetro de rota documentName é removido da rota do ponto de extremidade, a estrutura tenta resolver o nome do documento a partir do parâmetro de consulta. Não fornecer o documentName na rota ou na consulta pode resultar em um comportamento inesperado.

Personalizar o ponto de extremidade OpenAPI

Como o documento OpenAPI é servido por meio de um ponto de extremidade do manipulador de rota, qualquer personalização disponível para ponto de extremidade mínimos padrão estará disponível para o ponto de extremidade OpenAPI.

Limitar o acesso a documentos OpenAPI a usuários autorizados

O ponto de extremidade OpenAPI não permite nenhuma verificação de autorização por padrão. No entanto, as verificações de autorização podem ser aplicadas ao documento OpenAPI. No código a seguir, o acesso ao documento OpenAPI é limitado a quem possui a função tester:

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.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

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

app.Run();

Documento OpenAPI gerado pelo cache

O documento OpenAPI é gerado novamente sempre que uma solicitação ao ponto de extremidade OpenAPI é enviada. A regeneração permite que os transformadores incorporem o estado dinâmico do aplicativo em sua operação. Por exemplo, regenerar uma solicitação com detalhes do contexto HTTP. Quando aplicável, o documento OpenAPI pode ser armazenado em cache para evitar a execução do pipeline de geração de documentos em cada solicitação HTTP.

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

app.MapOpenApi()
    .CacheOutput();

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

app.Run();

Gerar documentos OpenAPI em tempo de compilação

Em aplicativos da Web típicos, os documentos OpenAPI são gerados em tempo de execução e servidos por meio de uma solicitação HTTP para o servidor de aplicativos.

Em alguns cenários, é útil gerar o documento OpenAPI durante a etapa de build do aplicativo. Esses cenários incluem:

• Gerar documentação OpenAPI confirmada no controle do código-fonte.
• Gerar documentação do OpenAPI que é usada para testes de integração baseados em especificações.
• Gerar documentação OpenAPI que é servida estaticamente a partir do servidor web.

Para adicionar suporte para a geração de documentos OpenAPI no momento da compilação, instale o pacote Microsoft.Extensions.ApiDescription.Server:

Visual Studio

Execute o seguinte comando no Console do Gerenciador de Pacotes:

Install-Package Microsoft.Extensions.ApiDescription.Server

CLI do .NET

Execute o seguinte comando no diretório que contém o arquivo de projeto:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Após a instalação, esse pacote gerará automaticamente o(s) documento(s) da API aberta associado(s) ao aplicativo durante a compilação e os preencherá no diretório de saída do aplicativo.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Personalizando a geração de documentos em tempo de compilação

Modificando o diretório de saída do arquivo Open API gerado

Por padrão, o documento OpenAPI gerado será emitido para o diretório de saída do aplicativo. Para modificar o local do arquivo emitido, defina o caminho de destino na OpenApiDocumentsDirectory propriedade.

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

O valor de é resolvido em relação ao arquivo de OpenApiDocumentsDirectory projeto. O uso do ./ valor acima emitirá o documento OpenAPI no mesmo diretório que o arquivo de projeto.

Modificando o nome do arquivo de saída

Por padrão, o documento OpenAPI gerado terá o mesmo nome que o arquivo de projeto do aplicativo. Para modificar o nome do arquivo emitido, defina o --file-name OpenApiGenerateDocumentsOptions argumento na propriedade.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Selecionando o documento OpenAPI a ser gerado

Alguns aplicativos podem ser configurados para emitir vários documentos OpenAPI, para várias versões de uma API ou para distinguir entre APIs públicas e internas. Por padrão, o gerador de documentos em tempo de compilação emitirá arquivos para todos os documentos configurados em um aplicativo. Para emitir apenas um único nome de documento, defina o --document-name OpenApiGenerateDocumentsOptions argumento na propriedade.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Personalizando o comportamento de tempo de execução durante a geração de documentos de tempo de compilação

Nos bastidores, a geração de documentos OpenAPI em tempo de compilação funciona iniciando o ponto de entrada do aplicativo com uma implementação de servidor inerte. Este é um requisito para produzir documentos OpenAPI precisos, pois todas as informações no documento OpenAPI não podem ser analisadas estaticamente. Como o ponto de entrada do aplicativo é invocado, qualquer lógica na inicialização dos aplicativos será invocada. Isso inclui código que injeta serviços no contêiner de DI ou lê da configuração. Em alguns cenários, é necessário restringir os caminhos de código que serão executados quando o ponto de entrada do aplicativo estiver sendo invocado da geração de documentos em tempo de build. Esses cenários incluem:

• Não lendo determinadas strings de configuração.
• Não registrar serviços relacionados ao banco de dados.

Para impedir que esses caminhos de código sejam invocados pelo pipeline de geração em tempo de build, eles podem ser condicionados por trás de uma verificação do assembly de entrada da seguinte forma:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}