[C#] Swagger를 이용한 ASP.net core Web API 문서 생성

용용이·2023년 4월 3일

C#

목록 보기

3/3

Swagger

스웨거(Swagger)는 개발자가 REST 웹서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

즉, 스웨거는 대표적인 API 관리 도구로 개발한 RESP API 도구를 편리하게 문서화해주며 편리하게 API를 호출하고 테스트 할 수 있는 도구입니다. -위키백과-

• OpenAPI를 구현하기 위한 도구

• API들이 갖고 있는 명세을 정의할 수 있는 Tool

• API 사용 방법을 사용자에게 알려주는 문서

Swagger 기능

1) API Design (API 설계)

: Swagger-editor를 통해 api를 문서화하고 빠르게 명세 가능

2) API Development

: Swagger-codepen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화할 수 있도록 도와준다.

3) API Documentation

: Swagger-UI를 통해 작성된 API를 시각화시켜준다.

4) API Testing

: Swagger-Inspector를 통해 API를 시각화하고 빠른 테스팅을 진행할 수 있다.

5) Standardize

: Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유하는 Hub

실습

다음으로 Visual Studio를 이용하여 간단하게 Swagger를 활용하여 API 문서를 생성해 보겠습니다.

ASP.NET Core 웹 API 템플릿을 선택합니다.

프로젝트 이름은 SwaggerTest로 하여 프로젝트를 생성해 보겠습니다.

이전에는 Swagger를 이용하기 위해서 NuGet 패키지를 이용하여 Swashbuckle을 추가하여야 했는데 현재는 기본 탬플릿에 적용이 되어있어 따로 Nuget 패키지를 추가하는 부분은 진행하지 않겠습니다.

기존 컨트롤러에는 GET에 대한 요청에 대한 동작만 정의되어 있는데 POST, PUT, DELETE 메서드도 추가해 보도록 하겠습니다.

using Microsoft.AspNetCore.Mvc;

namespace SwaggerTest.Controllers
{
    enum Method
    {
        Get,
        Post, 
        Put,
        Delete
    }

    [ApiController]
    [Route("[controller]")]
    public class SwaggerTestController : ControllerBase
    {
        [HttpGet(Name = "Get")]
        public string Get()
        {
            return Method.Get.ToString();
        }

        [HttpPost(Name = "Post")]
        public string PostTest()
        {
            return Method.Post.ToString();
        }

        [HttpPut(Name = "Put")]
        public string Put()
        {
            return Method.Put.ToString();
        }

        [HttpDelete(Name = "Delete")]
        public string Delete()
        {
            return Method.Delete.ToString();
        }
    }
}

위와 같이 컨트롤러 수정 후 프로젝트를 실행해 보겠습니다.

GET, POST, PUT, DELETE 메서드가 추가로 생성된 부분을 확인할 수 있습니다.