연습 - Swashbuckle을 사용하여 Open API 문서 만들기 - Training

8분

이 연습에서는 ASP.NET Core Web API 애플리케이션에 Swagger 및 Swagger UI를 추가합니다. Swagger 도구는 웹 API를 설명하는 OpenAPI 문서를 만드는 데 도움이 됩니다.

참고

로컬 컴퓨터에 소스 코드를 다운로드하여 이 연습을 완료합니다. 파일을 다운로드한 후에는 파일의 압축을 풀어야 합니다.

다운로드: ASP.NET Core Web API 애플리케이션.

화면 오른쪽 가운데에서 다운로드 단추를 선택합니다.
exercise.zip 파일의 압축을 풉니다.

Swagger 도구 추가

Visual Studio를 열고 ASP.NET Core Web API 앱을 찾습니다.
솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리를 선택합니다.
NuGet 패키지 관리자에서 Swashbuckle.AspNetCore를 검색합니다. 패키지를 선택하고 설치합니다.

이제 NuGet 패키지가 설치되었습니다. NuGet 패키지 관리자 탭을 닫습니다.

OpenAPI 문서를 생성하도록 Swashbuckle 구성

Startup.cs 파일을 엽니다.

namespace InventoryManagement.ApiApp 줄 바로 위에 다음 지시문을 추가합니다.

/* === using directive BEGIN === */
using Microsoft.OpenApi.Models;
/* === using directive END === */

ConfigureServices(IServiceCollection) 메서드 내부의 모든 코드를 다음 코드로 바꿉니다.

    services.AddControllers();

    /* === SwaggerGen BEGIN === */
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
    });
    /* === SwaggerGen END === */

Configure(IApplicationBuilder, IWebHostEnvironment) 메서드 내에서 if (env.IsDevelopment()) 조건문을 찾아 해당 문 위의 모든 항목을 다음 코드로 바꿉니다.
```
    /* === SwaggerUI BEGIN === */
    app.UseSwagger(c =>
    {
        c.PreSerializeFilters.Add((swagger, httpReq) => {
            var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
            swagger.Servers = new List<OpenApiServer>() { server };
        });
    });
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
    /* === SwaggerUI END === */
```
참고 항목

Swagger 엔드포인트는 개발 환경에서만 사용하도록 설정되는 것이 매우 중요합니다. 그렇지 않으면 API가 대중에게 노출될 수 있습니다.

이제 ASP.NET Core Web API 앱에 대한 OpenAPI 문서 기능 활성화를 완료했습니다. Startup.cs 파일을 저장합니다. 다음 스크린샷과 비슷한 변경 사항이 표시됩니다.

OpenAPI 문서 파일 생성

Visual Studio 중앙 위쪽에서 디버그 단추를 선택합니다.

웹 브라우저가 자동으로 열리고 Swagger UI 페이지가 표시됩니다.

404 오류 페이지가 표시될 수도 있습니다. 이 경우 브라우저의 주소 표시줄에 URL(https://localhost:<port_number>/swagger)을 입력합니다. 예를 들어 다음 스크린샷에서 URL은 https://localhost:44371/swagger입니다.
링크를 선택하여 OpenAPI 문서 페이지를 엽니다.
OpenAPI 문서가 즉석에서 렌더링됩니다.

이제 ASP.NET Core Web API 앱이 OpenAPI 문서를 생성할 준비가 되었습니다.

계속

연습 - Swashbuckle을 사용하여 Open API 문서 만들기

Swagger 도구 추가

OpenAPI 문서를 생성하도록 Swashbuckle 구성

OpenAPI 문서 파일 생성

피드백