Spring Swagger 를 사용하여 API 명세서 작성 자동화하기

jjunhwan.kim·2023년 10월 15일

Spring Swagger 스프링

스프링

목록 보기

4/10

개요

지난 글에서 Spring REST Docs를 사용하여 API 명세서 작성 자동화를 알아보았습니다.
이번 글에서는 Swagger를 사용하여 API 명세서를 작성해보겠습니다.
Spring REST Docs는 테스트 코드를 작성하여 API 명세서를 HTML 문서로 출력해줍니다.
Spring REST Docs는 단순 문서를 제공하고 Swagger는 API를 테스트 할 수 있는 UI를 제공합니다.

프로젝트 생성

먼저 스프링 프로젝트를 생성합니다. https://start.spring.io 에서 아래와 같이 Spring Web, Lombok 의존성을 추가하여 생성합니다.
저번 예제와 동일하게 이번 예제에서도 API만 구현하므로 데이터베이스 관련 의존성은 추가하지 않았습니다.

springdoc-openapi 의존성 추가

build.gradle 파일에 springdoc-openapi-starter-webmvc-ui 의존성을 추가합니다.

springdoc-openapi 라이브러리는 Swagger는 아닙니다. 공식 문서 https://springdoc.org 를 참고하면, springdoc-openapi 라이브러리는 런타임에 애플리케이션을 분석하여 JSON/YAML 및 HTML 형식의 API를 자동으로 생성합니다(OpenAPI 3). Swagger UI는 OpenAPI으로 화면을 구성하여 보여줍니다.

springdoc-openapi 라이브러리는 swagger-annotations 과 swagger-ui 공식 라이브러리에 의존한다고 합니다.
springdoc과 비슷한 라이브러리로 springfox가 있으나 2020년 이후로 업데이트가 되지 않아 사용하지 않는 추세라고합니다.

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.1.4'
	id 'io.spring.dependency-management' version '1.1.3'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
	sourceCompatibility = '17'
}

configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
	useJUnitPlatform()
}

API 문서 확인

의존성을 추가하고 애플리케이션을 실행하고 아래 주소로 접속하면 API 문서가 출력됩니다.
http://localhost:8080/swagger-ui/index.html
API가 없는 상태이므로 빈 화면이 출력됩니다.

API 작성

이전 Spring REST Docs 글에서 사용했던 게시판 예제를 그대로 사용합니다.
게시글 생성, 조회, 업데이트, 삭제 API를 작성해보겠습니다.

먼저 API 공통 응답 포맷을 사용하기 위해 아래와 같이 CommonResponse 제네릭 클래스를 작성합니다.

Result enum 입니다.

게시글 목록 조회, 게시글 조회, 게시글 생성, 게시글 업데이트, 게시글 삭제 API를 아래와 같이 작성합니다.

PostService 클래스에는 비즈니스 로직을 작성합니다. 저는 일단 null만 리턴하도록 구현하였습니다.

API 문서 확인

API를 추가하고 다시 애플리케이션을 실행시킵니다. 문서를 다시 확인해보면 (http://localhost:8080/swagger-ui/index.html) 아래와 같이 출력됩니다.

각 메서드에서 Try it out 버튼을 통해 직접 API를 호출할 수 있습니다. 따라서 포스트맨과 같은 툴 처럼 API를 테스트 할 수 있습니다.

Swagger 어노테이션

위의 API 문서에서는 각 API의 이름, 설명 등이 모두 스프링 기본 어노테이션을 기반으로 출력됩니다. Swagger 어노테이션을 추가하여 좀 더 상세 정보를 표시할 수 있습니다.

@Tag, @Operation, @ApiResponse, @Parameter 네 가지 어노테이션을 통해 API와 각 API의 파라미터에 상세 정보를 추가하였습니다.

자세한 내용은 https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations 문서를 참고 바랍니다.

다시 애플리케이션을 실행하면 아래와 같이 출력됩니다. 각 파라미터와 응답에 대한 설명이 추가되었습니다.

Spring REST Docs VS Swagger

Swagger는 UI를 통해 API 명세를 확인함과 동시에 테스트도 할 수 있는 장점이 있습니다. 하지만 컨트롤러 코드에 Swagger 어노테이션 코드가 추가되어 애플리케이션 코드와 API 명세를 위한 코드가 동시에 존재하는 단점이 있습니다.
스프링 REST Docs는 테스트 코드 기반으로 문서를 생성하므로 애플리케이션 코드와 API 명세를 위한 코드가 분리됩니다. 하지만 정적인 문서만 생성하므로 Swagger처럼 테스트는 불가능합니다.