openAPI 문서 사용
로컬 임시 테스트에 Swagger UI 사용
기본적으로 패키지는 Microsoft.AspNetCore.OpenApi OpenAPI 문서를 시각화하거나 상호 작용하기 위한 기본 제공 지원으로 제공되지 않습니다. OpenAPI 문서를 시각화하거나 상호 작용하기 위한 인기 있는 도구에는 Swagger UI 및 ReDoc가 포함됩니다. Swagger UI 및 ReDoc는 여러 가지 방법으로 앱에 통합할 수 있습니다. Visual Studio 및 VS Code와 같은 편집기에서는 OpenAPI 문서에 대해 테스트하기 위한 확장 및 기본 제공 환경을 제공합니다.
이 패키지는 Swashbuckle.AspNetCore.SwaggerUi 앱에서 사용할 Swagger UI의 웹 자산 번들을 제공합니다. 이 패키지를 사용하여 생성된 문서에 대한 UI를 렌더링할 수 있습니다. 이를 구성하려면 다음을 수행합니다.
Swashbuckle.AspNetCore.SwaggerUi패키지를 설치합니다.- 이전에 등록된 OpenAPI 경로에 대한 참조를 사용하여 swagger-ui 미들웨어를 사용하도록 설정합니다.
- 정보 공개 및 보안 취약성을 제한하려면 개발 환경에서만 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "v1");
});
}
app.MapGet("/", () => "Hello world!");
app.Run();
대화형 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference();
}
app.MapGet("/", () => "Hello world!");
app.Run();
Spectral을 사용하여 Lint에서 생성한 OpenAPI 문서
스펙트럼 은 오픈 소스 OpenAPI 문서 linter입니다. Spectral을 앱 빌드에 통합하여 생성된 OpenAPI 문서의 품질을 확인할 수 있습니다. 패키지 설치 지침에 따라 스펙트럼을 설치합니다.
Spectral을 활용하려면 빌드 시간 OpenAPI 문서 생성을 사용하도록 패키지를 설치 Microsoft.Extensions.ApiDescription.Server 합니다.
앱 .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)
.NET 6, 7 또는 8의 최소 API에서 생성된 OpenAPI 문서를 사용하는 방법을 알아보려면 Swagger 및 NSwag 개요를 참조하세요.
ASP.NET Core