openAPI 문서 사용

로컬 임시 테스트에 Swagger UI 사용

기본적으로 Microsoft.AspNetCore.OpenApi 패키지는 OpenAPI 문서를 시각화하거나 상호 작용하기 위한 내장된 지원을 포함하지 않습니다. OpenAPI 문서를 시각화하거나 상호 작용하기 위한 인기 있는 도구에는 Swagger UI 및 ReDoc가 포함됩니다. Swagger UI 및 ReDoc는 여러 가지 방법으로 앱에 통합할 수 있습니다. Visual Studio 및 Visual Studio Code와 같은 편집기에서는 OpenAPI 문서에 대해 테스트하기 위한 확장 및 기본 제공 환경을 제공합니다.

Swagger UI의 웹 자산 번들로 앱에서 사용할 수 있도록 제공하는 Swashbuckle.AspNetCore.SwaggerUi 패키지입니다. 이 패키지를 사용하여 생성된 문서에 대한 UI를 렌더링할 수 있습니다. 이를 구성하려면 다음을 수행합니다.

• Swashbuckle.AspNetCore.SwaggerUi 패키지를 설치합니다.
• 이전에 등록된 OpenAPI 경로에 대한 참조를 사용하여 swagger-ui 미들웨어를 사용하도록 설정합니다.

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

정보 공개를 제한하는 보안 모범 사례로 OpenAPI 사용자 인터페이스(Swagger UI, ReDoc, Scalar)는 개발 환경에서만 사용하도록 설정해야 합니다. 예를 들어 Swagger OAuth 2.0 구성을 참조하세요.

앱을 시작하고 https://localhost:<port>/swagger로 이동하여 Swagger UI를 확인하세요.

Swagger UI URL에서 https의 Properties/launchSettings.json 프로필을 사용하여 앱을 자동으로 시작하려면 다음을 수행하십시오:

• launchBrowser이 사용 설정되어 있는지 확인합니다 (true).
• launchUrl를 swagger로 설정합니다.

"launchBrowser": true,
"launchUrl": "swagger",

대화형 API 설명서에 스칼라 사용

스칼라는 OpenAPI용 오픈 소스 대화형 문서 UI입니다. 스칼라는 ASP.NET Core에서 제공하는 OpenAPI 엔드포인트와 통합할 수 있습니다. 스칼라를 구성하려면 패키지를 설치합니다 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();

앱을 시작한 후 https://localhost:<port>/scalar으로 탐색하여 스칼라 UI를 보십시오.

다음 프로필을 https사용하여 Properties/launchSettings.json 스칼라 UI URL에서 앱을 자동으로 시작하려면

• launchBrowser이 사용 설정되어 있는지 확인합니다 (true).
• launchUrl를 scalar로 설정합니다.

"launchBrowser": true,
"launchUrl": "scalar",

Spectral을 사용하여 Lint에서 생성한 OpenAPI 문서

스펙트럼 은 오픈 소스 OpenAPI 문서 linter입니다. Spectral을 앱 빌드에 통합하여 생성된 OpenAPI 문서의 품질을 확인할 수 있습니다. 패키지 설치 지침에 따라 스펙트럼을 설치합니다.

먼저 Microsoft.Extensions.ApiDescription.Server 패키지를 설치하여, 빌드 시 OpenAPI 문서를 linting하는 데 Spectral을 활용할 수 있도록 설정합니다.

앱 .csproj 파일에서 다음 속성을 설정하여 빌드 시 문서 생성을 사용하도록 설정합니다."

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

실행 dotnet build 하여 문서를 생성합니다.

dotnet build

다음 내용이 포함된 .spectral.yml 파일을 만듭니다.

extends: ["spectral:oas"]

spectral lint을(를) 생성된 파일에서 실행합니다.

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)

주입 지원 IOpenApiDocumentProvider

종속성 주입을 통해 서비스에 삽입 IOpenApiDocumentProvider 하여 HTTP 요청 컨텍스트 외부에서도 프로그래밍 방식으로 OpenAPI 문서에 액세스할 수 있습니다.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

DI 컨테이너에 서비스를 등록합니다.

builder.Services.AddScoped<DocumentService>();

이렇게 하면 클라이언트 SDK 생성, 백그라운드 프로세스에서 API 계약의 유효성 검사 또는 외부 시스템으로 문서 내보내기 등의 시나리오가 가능합니다.

주입 IOpenApiDocumentProvider 에 대한 지원은 .NET 10의 ASP.NET Core에서 도입되었습니다. 자세한 내용은 dotnet/aspnetcore #61463을 참조하세요.