C# Academy · Aula

Gerando documentos OpenAPI

Produza especificações de API legíveis por máquinas.

Gerando documentos OpenAPI é uma aula grátis de C# Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de C# Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de C# Academy inclui 4 aulas no total.

O que é OpenAPI?

OpenAPI é uma descrição padronizada e legível por máquinas de uma API HTTP. A partir dela, você pode gerar documentação, SDKs de cliente e ferramentas de teste.

O .NET 9 oferece geração integrada de documentos OpenAPI, substituindo a dependência antiga do Swashbuckle em muitos aplicativos.

// OpenAPI document = JSON describing paths, schemas, params

O pacote Microsoft.AspNetCore.OpenApi

O suporte integrado está no pacote Microsoft.AspNetCore.OpenApi. Nos modelos do .NET 9, ele já é referenciado.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registre o gerador de documentos com AddOpenApi na configuração dos serviços.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi disponibiliza o documento gerado em um ponto de extremidade. Por padrão, ele é disponibilizado em /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Restringindo ao ambiente de desenvolvimento

É comum disponibilizar o documento somente no ambiente de desenvolvimento para evitar expor a superfície da sua API em produção.

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

Descrevendo pontos de extremidade

Os metadados do OpenAPI são enriquecidos a partir do seu código. Use WithSummary, WithDescription e WithTags nos pontos de extremidade de APIs mínimas.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Documentando respostas

Declare os tipos de resposta e os códigos de status para que o documento os liste com precisão.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Transformadores de documentos

Personalize todo o documento — título, versão e servidores — com um transformador de documento passado para AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Transformadores de operações

Um transformador de operação ajusta operações individuais — por exemplo, adicionando um parâmetro de cabeçalho comum a cada ponto de extremidade.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Adicionando uma interface

O gerador integrado produz o documento JSON, mas não uma interface. Combine-o com um visualizador, como Scalar ou Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Gerando no momento da compilação

Você pode gerar o arquivo OpenAPI durante a compilação, sem um servidor em execução, usando as ferramentas Microsoft.Extensions.ApiDescription.Server, o que é útil para a geração de clientes em CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Verificação rápida

Confirme os conceitos básicos de OpenAPI no .NET 9.

Recapitulação

Você gerou documentos OpenAPI:

AddOpenApi() registra o gerador; MapOpenApi() disponibiliza o JSON.
Enriqueça os pontos de extremidade com WithSummary, Produces e marcas.
Os transformadores de documentos e de operações personalizam a saída.
Combine-os com Scalar ou Swagger UI para obter uma visualização interativa.

Próximo tópico: documentar APIs versionadas.

Perguntas Frequentes

A aula “Gerando documentos OpenAPI” é grátis?

Sim — o texto completo de “Gerando documentos OpenAPI” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de C# Academy, atualize para CoddyKit PRO. O curso de C# Academy inclui 4 aulas no total.

O que vou aprender em “Gerando documentos OpenAPI”?

Produza especificações de API legíveis por máquinas. Você pratica C# Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar C# Academy?

Nenhuma experiência prévia é necessária. C# Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Gerando documentos OpenAPI”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de C# Academy?

Sim. Cada aula de C# Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para C# Academy