Swagger를 이용한 ASP.net core의 web api 문서 생성 및 디버깅

Swagger를 이용한 ASP.NET core web api 문서 생성 및 테스트/디버깅

Restful API를 테스트하기 위하여 포스트맨 (postman)을 주로 사용하였습니다. 이번에는 api문서를 자동으로 생성하고 테스트 할 수 있는 swagger를 asp.net core web api에 적용하는 방법을 살펴보겠습니다.

샘플로 작업할 asp.net core web api 프로젝트는 여기에서 다운로드 받아서 설치하도록 합니다.

swagger

• 스웨거는 API 개발 툴의 프레임워크입니다.
• OpenAPI를 준수하고 설계, 개발, 문서화, 개발 및 테스트를 지원합니다.
• 자세한 내용은 https://swagger.io에서 참조합니다.

Swashbuckle

aspnet core에서 swagger를 이용하기 위하여 swashbuckle을 이용합니다. 세가지 요소는 다음과 같습니다.

• Swashbuckle.AspNetCore.Swagger - 개체모델 및 미들웨어
• Swashbuckle.AspNetCore.SwaggerGen - 개체를 빌드하는 생성기
• Swashbuckle.AspNetCore.SwaggerUI - 생성기에서 생성된 json을 해석하여 UI로 표출

NuGet 패키지를 이용하여 Swashbuckle 추가

페키지 관리자 콘솔(Package Manager Console)에서 다음을 실행합니다.

PM> Install-Package Swashbuckle.AspNetCore

Swagger 서비스 추가

Startup.cs의 ConfigureService 메서드에서 Swagger생성기 서비스를 추가합니다. (services.AddSwaggerGen)

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));
            services.AddMvc();

            // Swagger생성기 서비스를 추가
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
                {
                    Title = "Todo Service API",
                    Version = "v1"
                });
            });
        }

Startup.cs의 Configure 메서드에 SwaggerUI 사용을 설정합니다.

        public void Configure(IApplicationBuilder app)
        {
            // Swagger 사용
            app.UseSwagger();
            // SwaggerUI 사용
            app.UseSwaggerUI(c =>
            {
                // swagger가 생성한 json에 접근할 수 있는 url
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Todo Service API V1");
            });
            app.UseMvc();
        }

API앱을 실행하면 웹브라우져가 http://localhost:56877로 이동합니다. 여기에 /swagger/v1/swagger.json를 덧붙이면 다음과 같이 swagger에 의하여 생성된 json파일을 볼 수 있습니다.

API 문서

http://localhost:56877/swagger/로 이동하면 swaggerUI에 의하여 생성된 API문서를 볼 수 있습니다.

##API 실행

Api 메소드를 클릭하면 해당 메소드의 세부사항 내역을 볼 수 있습니다. Try it out 버튼을 클릭하여 메소드를 테스트할 수 있습니다.

미리 해당 메소드에 대하여 브레이크 포인트를 걸어두면 메소드를 실행하여 디버깅을 시작할 수 있습니다.

SwaggerUI에 대한 커스터마이징

문서에 대한 Description 및 license의 보충 설명을 추가할 수 있습니다.

http요청에 대한 응답의 형식 정의

Produces 속성을 추가함으로서 응답 컨텐츠 형식을 정의할 수 있습니다.

namespace TodoApi.Controllers
{
    [Produces("application/json")]
    [Route("api/[controller]")]
    public class TodoController : Controller
    {
        private readonly TodoContext _context;

Http Reponse Code 지정

Create 메소드 실행에 대한 Http Response Code 값을 ProducesResponseType을 통하여 지정할 수 있습니다.

        [HttpPost]
        [ProducesResponseType(typeof(TodoItem), 201)]
        [ProducesResponseType(typeof(TodoItem), 400)]
        public IActionResult Create([FromBody] TodoItem item)