OpenAPI 문서 생성

OpenAPI란 무엇인가요

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

Microsoft.AspNetCore.OpenApi 패키지

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

var app = builder.Build();

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

app.Run();

개발 환경으로 제한하기

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

엔드포인트 설명 추가

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

응답 문서화

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

문서 변환기

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

작업 변환기

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

사용자 인터페이스 추가

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

빌드 시점에 생성하기

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

빠른 확인

복습