ASP.NET Core API 앱에서의 OpenAPI 지원

ASP.NET Core는 컨트롤러 기반 및 최소 API 앱에서 OpenAPI 문서 생성을 지원합니다. OpenAPI 사양은 HTTP API를 문서화하기 위한 프로그래밍 언어 독립적 표준입니다. 이 표준은 기본 제공 API와 오픈 소스 라이브러리의 조합을 통해 ASP.NET Core 앱에서 지원됩니다. 애플리케이션에서 OpenAPI 통합에는 다음과 같은 세 가지 주요 측면이 있습니다.

• 앱의 엔드포인트에 대한 정보 생성.
• OpenAPI 스키마와 일치하는 형식으로 정보 수집.
• 시각적 UI 또는 직렬화된 파일을 통해 생성된 OpenAPI 문서를 노출합니다.

ASP.NET Core 앱은 패키지를 통해 Microsoft.AspNetCore.OpenApi 앱의 엔드포인트에 대한 정보를 생성하기 위한 기본 제공 지원을 제공합니다.

다음 코드는 ASP.NET Core 최소 웹 API 템플릿에서 생성되며 OpenAPI를 사용합니다.

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

앞의 강조 표시된 코드에서 다음을 수행합니다.

• AddOpenApi 는 OpenAPI 문서 생성에 필요한 서비스를 애플리케이션의 DI 컨테이너에 등록합니다.
• MapOpenApi 는 JSON으로 직렬화된 OpenAPI 문서를 보기 위해 애플리케이션에 엔드포인트를 추가합니다. OpenAPI 엔드포인트는 중요한 정보를 노출하는 위험을 최소화하고 프로덕션의 취약성을 줄이기 위해 개발 환경으로 제한됩니다.

Microsoft.AspNetCore.OpenApi NuGet 패키지

패키지는 Microsoft.AspNetCore.OpenApi 다음과 같은 기능을 제공합니다.

• 런타임에 OpenAPI 문서를 생성하고 애플리케이션의 엔드포인트를 통해 액세스할 수 있도록 지원합니다.
• 생성된 문서를 수정할 수 있는 "변환기" API를 지원합니다.

패키지를 사용 Microsoft.AspNetCore.OpenApi 하려면 프로젝트 파일에 PackageReference로 추가합니다.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

패키지에 대한 Microsoft.AspNetCore.OpenApi 자세한 내용은 OpenAPI 문서 생성을 참조 하세요.

Microsoft.Extensions.ApiDescription.Server NuGet 패키지

패키지는 Microsoft.Extensions.ApiDescription.Server 빌드 시 OpenAPI 문서를 생성하고 직렬화할 수 있도록 지원합니다.

사용 Microsoft.Extensions.ApiDescription.Server하려면 프로젝트 파일에 PackageReference로 추가합니다. 빌드 시 문서 생성은 속성을 설정하여 사용하도록 설정됩니다 OpenApiGenerateDocuments . 기본적으로 생성된 OpenAPI 문서는 디렉터리에 저장 obj 되지만 속성을 설정 OpenApiDocumentsDirectory 하여 출력 디렉터리를 사용자 지정할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

GitHub의 ASP.NET Core OpenAPI 소스 코드

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

추가 리소스

• 최소 API의 인증 및 권한 부여

OpenAPI 사양은 HTTP API를 문서화하기 위한 프로그래밍 언어 독립적 표준입니다. 이 표준은 기본 제공 API와 오픈 소스 라이브러리의 조합을 통해 최소 API에서 지원됩니다. 애플리케이션에서 OpenAPI 통합에는 다음과 같은 세 가지 주요 측면이 있습니다.

• 앱의 엔드포인트에 대한 정보 생성.
• OpenAPI 스키마와 일치하는 형식으로 정보 수집.
• 시각적 UI 또는 직렬화된 파일을 통해 생성된 OpenAPI 스키마 노출.

최소 API는 Microsoft.AspNetCore.OpenApi 패키지를 통해 앱의 엔드포인트에 대한 정보를 생성하기 위한 기본 제공 지원을 제공합니다. 시각적 UI를 통해 생성된 OpenAPI 정의를 노출하려면 타사 패키지가 필요합니다.

컨트롤러 기반 API에서 OpenAPI 지원에 대한 자세한 내용은 이 문서의 .NET 9 버전을 참조 하세요.