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 VS 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/v1 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/v1.

"launchBrowser": true,
"launchUrl": "scalar/v1",

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, instale o pacote Microsoft.Extensions.ApiDescription.Server para habilitar a 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)