OpenAPI 문서 생성

이 패키지는 Microsoft.AspNetCore.OpenApi ASP.NET Core에서 OpenAPI 문서 생성을 기본적으로 지원합니다. 패키지는 다음과 같은 기능을 제공합니다.

• 런타임에 OpenAPI 문서를 생성하고 애플리케이션의 엔드포인트를 통해 액세스할 수 있도록 지원합니다.
• 생성된 문서를 수정할 수 있는 "변환기" API를 지원합니다.
• 단일 앱에서 여러 OpenAPI 문서 생성을 지원합니다.
• 에서 제공하는 System.Text.JsonJSON 스키마 지원을 활용합니다.
• 네이티브 AoT와 호환됩니다.

패키지 설치

Microsoft.AspNetCore.OpenApi 패키지를 설치합니다.

Visual Studio

패키지 관리자 콘솔에서 다음 명령을 실행합니다.

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

다음 명령을 실행합니다.

dotnet add package Microsoft.AspNetCore.OpenApi

OpenAPI 문서 생성 구성

코드는 다음과 같습니다.

• OpenAPI 서비스를 추가합니다.
• 엔드포인트가 JSON 형식으로 OpenAPI 문서를 볼 수 있도록 합니다.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

앱을 시작하고 생성된 OpenAPI 문서를 보려면 이동합니다 https://localhost:<port>/openapi/v1.json .

OpenAPI 문서 생성을 사용자 지정하는 옵션

다음 섹션에서는 OpenAPI 문서 생성을 사용자 지정하는 방법을 보여 줍니다.

OpenAPI 문서 이름 사용자 지정

앱의 각 OpenAPI 문서에는 고유한 이름이 있습니다. 등록된 기본 문서 이름은 .입니다 v1.

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

호출에 매개 변수로 이름을 전달하여 문서 이름을 수정할 AddOpenApi 수 있습니다.

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

문서 이름은 OpenAPI 구현의 여러 위치에 표시됩니다.

생성된 OpenAPI 문서를 가져올 때 문서 이름은 요청에서 documentName 매개 변수 인수로 제공됩니다. 다음 요청은 해당 및 v1 문서를 확인 internal 합니다.

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

생성된 문서의 OpenAPI 버전 사용자 지정

기본적으로 OpenAPI 문서 생성은 OpenAPI 사양의 v3.0을 준수하는 문서를 만듭니다. 다음 코드는 OpenAPI 문서의 기본 버전을 수정하는 방법을 보여 줍니다.

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

OpenAPI 엔드포인트 경로 사용자 지정

기본적으로 호출 MapOpenApi 을 통해 등록된 OpenAPI 엔드포인트는 엔드포인트에 /openapi/{documentName}.json 문서를 노출합니다. 다음 코드는 OpenAPI 문서가 등록된 경로를 사용자 지정하는 방법을 보여 줍니다.

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

엔드포인트 경로에서 경로 매개 변수를 documentName 제거할 수는 있지만 권장되지는 않습니다. 경로 매개 변수가 documentName 엔드포인트 경로에서 제거되면 프레임워크는 쿼리 매개 변수에서 문서 이름을 확인하려고 시도합니다. 경로 또는 쿼리에 제공하지 documentName 않으면 예기치 않은 동작이 발생할 수 있습니다.

OpenAPI 엔드포인트 사용자 지정

OpenAPI 문서는 경로 처리기 엔드포인트를 통해 제공되므로 표준 최소 엔드포인트에서 사용할 수 있는 모든 사용자 지정을 OpenAPI 엔드포인트에서 사용할 수 있습니다.

OpenAPI 문서 액세스를 권한 있는 사용자로 제한

OpenAPI 엔드포인트는 기본적으로 권한 부여 검사를 사용하도록 설정하지 않습니다. 그러나 권한 부여 검사는 OpenAPI 문서에 적용할 수 있습니다. 다음 코드에서 OpenAPI 문서에 대한 액세스는 역할이 있는 문서로 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();

생성된 OpenAPI 문서 캐시

OpenAPI 엔드포인트에 대한 요청이 전송될 때마다 OpenAPI 문서가 다시 생성됩니다. 다시 생성을 통해 변환기는 동적 애플리케이션 상태를 작업에 통합할 수 있습니다. 예를 들어 HTTP 컨텍스트의 세부 정보를 사용하여 요청을 다시 생성합니다. 해당하는 경우 각 HTTP 요청에서 문서 생성 파이프라인을 실행하지 않도록 OpenAPI 문서를 캐시할 수 있습니다.

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();

빌드 시 OpenAPI 문서 생성

일반적인 웹 애플리케이션에서 OpenAPI 문서는 런타임에 생성되고 애플리케이션 서버에 대한 HTTP 요청을 통해 제공됩니다.

일부 시나리오에서는 애플리케이션의 빌드 단계 중에 OpenAPI 문서를 생성하는 것이 유용합니다. 이 시나리오에는 다음이 포함됩니다.

• 소스 제어에 커밋된 OpenAPI 설명서 생성
• 사양 기반 통합 테스트에 사용되는 OpenAPI 설명서 생성
• 웹 서버에서 정적으로 제공되는 OpenAPI 설명서 생성

빌드 시 OpenAPI 문서 생성에 대한 지원을 추가하려면 패키지를 설치합니다 Microsoft.Extensions.ApiDescription.Server .

Visual Studio

패키지 관리자 콘솔에서 다음 명령을 실행합니다.

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

프로젝트 파일이 포함된 디렉터리에서 다음 명령을 실행합니다.

dotnet add package Microsoft.Extensions.ApiDescription.Server

설치 시 이 패키지는 빌드하는 동안 애플리케이션과 연결된 Open API 문서를 자동으로 생성하고 애플리케이션의 출력 디렉터리에 채웁니다.

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

빌드 시간 문서 생성 사용자 지정

생성된 Open API 파일의 출력 디렉터리 수정

기본적으로 생성된 OpenAPI 문서는 애플리케이션의 출력 디렉터리로 내보내됩니다. 내보낸 파일의 위치를 수정하려면 속성에서 OpenApiDocumentsDirectory 대상 경로를 설정합니다.

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

OpenApiDocumentsDirectory 값은 프로젝트 파일을 기준으로 확인됩니다. ./ 위의 값을 사용하면 프로젝트 파일과 동일한 디렉터리에 OpenAPI 문서가 내보내됩니다.

출력 파일 이름 수정

기본적으로 생성된 OpenAPI 문서는 애플리케이션의 프로젝트 파일과 동일한 이름을 갖습니다. 내보낸 파일의 이름을 수정하려면 속성에서 --file-name 인수를 OpenApiGenerateDocumentsOptions 설정합니다.

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

생성할 OpenAPI 문서 선택

다양한 버전의 API에 대해 여러 OpenAPI 문서를 내보내거나 공용 API와 내부 API를 구분하도록 일부 애플리케이션을 구성할 수 있습니다. 기본적으로 빌드 시간 문서 생성기는 애플리케이션에 구성된 모든 문서에 대한 파일을 내보냅니다. 단일 문서 이름에 대해서만 내보내려면 속성에서 --document-name 인수를 OpenApiGenerateDocumentsOptions 설정합니다.

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

빌드 시간 문서 생성 중 런타임 동작 사용자 지정

모의 서버 구현을 사용하여 앱 진입점을 시작하여 빌드 시간 OpenAPI 문서 생성 함수를 생성합니다. OpenAPI 문서의 모든 정보를 정적으로 분석할 수 없으므로 정확한 OpenAPI 문서를 생성하려면 모의 서버가 필요합니다. 앱 진입점이 호출되므로 앱 시작의 모든 논리가 호출됩니다. 여기에는 서비스를 DI 컨테이너에 주입하거나 구성을 읽는 코드가 포함됩니다. 일부 시나리오에서는 빌드 시간 문서 생성에서 앱 진입점을 호출할 때 실행되는 코드 경로를 제한해야 합니다. 이 시나리오에는 다음이 포함됩니다.

• 특정 구성 문자열에서 읽지 않습니다.
• 데이터베이스 관련 서비스를 등록하지 않습니다.

이러한 코드 경로가 빌드 시간 생성 파이프라인에서 호출되지 않도록 제한하기 위해, 엔트리 어셈블리에 대한 검사를 통해 조건을 설정할 수 있습니다.

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults 서비스 검색, 복원력, 상태 검사 및 OpenTelemetry와 같은 일반적인 .NET Aspire 서비스를 추가합니다.

트리밍 및 네이티브 AOT

ASP.NET Core의 OpenAPI는 트리밍 및 네이티브 AOT를 지원합니다. 다음 단계에서는 트리밍 및 네이티브 AOT를 사용하여 OpenAPI 앱을 생성 및 게시합니다.

새 ASP.NET Core Web API(네이티브 AOT) 프로젝트를 만듭니다.

dotnet new webapiaot

Microsoft.AspNetCore.OpenAPI 패키지를 추가합니다.

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

OpenAPI 문서를 생성할 수 있도록 Program.cs 업데이트합니다.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

앱을 게시합니다.

dotnet publish