Swagger 소개

Swagger는 REST API를 설계할 때 설계, 문서화, 테스트를 보조해주는 프레임워크입니다. 이때 스웨거가 참조하는 명세를 OpenAPI 형식이라고 합니다.

OpenAPI

OpenAPI Specification(OAS)은 REST API를 표현하기 위한 문서 표준입니다.

GET /api/users?id=1이라는 요청에 대해 GET이라는 HTTP 메소드, 요청 url /api/users, 파라미터 ?id=1의 요청과 응답 형태는 어떠하다~라는 것을 YAML or JSON로 작성한 명세입니다.

그래서 스웨거는 Swagger UI를 통해 OpenAPI를 보기 좋게 시각화하는 웹 뷰를 생성하고, Swagger Editor는 브라우저 환경에서 YAML or JSON으로 OpenAPI를 작성할 수 있게 해주는 등 스웨거 프레임워크는 OpenAPI 명세를 기준으로 다양한 기능들을 제공하고 있습니다.

.yml 기준으로 다음과 같은 구조를 갖습니다.

openapi: 3.0.4
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

위 문서에 대해 주 사용 요소는 다음과 같습니다.

구성 요소	설명
openapi	명세 버전 (예: 3.0.1, 3.1.0 등)
info	API 이름, 버전, 설명
paths	API 엔드포인트 목록 (GET, POST 등 포함)
parameters	경로/쿼리/헤더/쿠키 등의 요청 파라미터
responses	응답 코드 및 응답 구조 정의
components.schemas	DTO 또는 공통 객체의 정의 (모델 재사용 가능)
security	인증/인가 방식 정의 (JWT, API Key, OAuth 등)

각 구조에 대해 더 상세한 설명은 공식 문서에서 확인하실 수 있습니다. 위 예시에선 대표적인 것들만 정리했습니다.

---

코드 기반 문서화

테스트나 코드 생성 등 추가적인 기능을 제공한다고 이야기했지만 이번 포스트에서는 문서화 부분만 다룹니다.

Spring Boot 환경을 기준으로 설명합니다.

springdoc-openapi

springdoc-openapi라는 라이브러리를 이용하면 코드 기반으로 OpenAPI 명세를 자동으로 생성할 수 있습니다.

build.gradle에 다음 의존성을 추가하기만 하면 어노테이션을 통해 OpenAPI 명세를 생성할 수 있게 됩니다.

//작성일 기준 latest 2.8.9
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9'

application.yml에서 다음 설정을 통해 doc의 경로를 변경할 수 있습니다.

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

지금 적힌 path는 default로 사용되는 경로이므로 해당 경로를 사용한다면 따로 작성하지 않아도 됩니다.
설정에 사용되는 전체 속성은 공식 문서에서 확인하실 수 있습니다.

우선 다음 예시 REST API 컨트롤러를 하나 작성해봅니다.

@RestController
@RequestMapping("/hello")
public class SampleController {

    @GetMapping
    public String hello(@RequestParam String name) {
        return "Hello, " + name;
    }
}

그리고 서버를 실행하고 http://localhost:8080/swagger-ui.html에 접속하면 다음과 같이 자동으로 생성된 문서를 확인할 수 있습니다.

http://localhost:8080/v3/api-docs로 접속하면 JSON 작성된 명세도 확인할 수 있습니다.

어노테이션

다음 어노테이션들을 통해 OpenAPI 명세를 자동 생성하면서 문서 내용을 편집할 수 있습니다.

어노테이션	설명
@Operation	API 엔드포인트 설명
@Parameter	개별 파라미터 정보
@RequestBody	요청 본문에 대한 설명
@Schema	DTO 클래스 필드 설명
@Tag	API 그룹 묶기

위에서 사용했던 예제 컨트롤러에 어노테이션들을 추가해보면서 내용을 변경해보겠습니다.

@Tag(name = "예제 컨트롤러", description = "스웨거 예제 API")
@RestController
@RequestMapping("/hello")
public class SampleController {

    @Operation(summary = "Hello 출력", description = "Hello와 파라미터로 전달된 값을 출력합니다.")
    @GetMapping
    public String hello(
        @Parameter(description = "Hello 뒤에 출력할 문자열") @RequestParam String name
    ) {
        return "Hello, " + name;
    }
}

각 어노테이션, 속성으로 전달 된 값이 문서에 반영되었음을 확인할 수 있습니다.