Spring boot - Api docs 설정 (Swagger + OpenAPI)

이번 포스팅은 스프링부트에서 Api docs를 설정하는 방식에 대해 다룬다.

(아마 다음 포스팅은 GraphQL 설정 방식에 대해 다룰 듯 싶다.)

 

Api docs를 사용하기 있어, 먼저 해당 기능 사용을 돕는 라이브러리를 추가한다.

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    
    // Swagger 
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
    implementation 'org.springdoc:springdoc-openapi-starter-common:2.5.0'
    implementation 'io.swagger.core.v3:swagger-annotations:2.2.20'
    
    // 중략
}

여기서, org.springdoc의 버전은 1.8.0 | 2.3.0 | 2.5.0 이 존재하니 자신이 원하는 버전으로 설치하면 될 것 같다.

 

이후 Swagger UI 기본 경로 및 문서 경로를 설정한다.

// application.yml
springdoc:
    swagger-ui:
        enabled: true
        path: /swagger-ui.html // Swagger ui 접근 경로
        operationsSorter: method // 메소드 정렬
        tagsSorter: alpha // 태그 알파벳순 정렬
        tryItOutEnabled: true
        filter: true // 필터
        urls:
            - url: /v3/api-docs 
              name: Chessy API
    api-docs:
        enabled: true
        path: /v3/api-docs // open api 스펙 json 경로
    default-produces-media-type: application/json
    default-consumes-media-type: application/json

 

이후 각 컨트롤러에 

@Tag, @Operation 어노테이션으로 Swagger가 적용됨을 명시하며, 설명을 덧붙일 수 있다.

// AppController.java

package com.chessy.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.chessy.exception.CustomException;
import com.chessy.exception.ErrorCode;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "AppController", description = "기본 API")
@RestController
@RequestMapping("/api/")
public class AppController {
  @Operation(summary = "헬스 체커", description = "애플리케이션 상태 확인 API")
  @GetMapping("/")

  public String healthCheck() {
    return "ok";
  }

  @Operation(summary = "테스트 API", description = "예외 처리 테스트용 API")
  @GetMapping("/test")
  public String test() {
    throw new CustomException(ErrorCode.USER_NOT_FOUND);
  }

}

 

보통은 여기까지하면 아래 주소로 접속이 가능하다.

/swagger-ui.html

 

하지만, 언제든 api 버전 관리는 필요하기 때문에 커스텀 하는 방법도 소개한다.

// Spring.Config.java

@Configuration
public class SpringConfig implements WebMvcConfigurer {

  // 중략

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Test API") // 제목
            .version("1.0.0") // 버전
            .description("API 문서") // 설명
            .contact(new Contact()
                .name("zynoobb") // 작성자
                .email("jw9491@gmail.com")) // 연락처
            .license(new License()
                .name("Apache 2.0")
                .url("http://springdoc.org")));
  }
}

이와 같은 방식으로 해당 내용을 추가해줄 수 있다.

 

추가로, 위 html 주소를 일일히 외워쓰기 번거롭다면 아래와 같은 방법을 사용할 수 있다.

// SwaggerController.java

package com.**.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class SwaggerController {

  @GetMapping("/api")
  public String redirectSwagger() {
    return "redirect:/swagger-ui/index.html";
  }
}

/api 로 접속 시, 내 swagger 주소로 리디렉션하는 방식으로 

URI 뒤에 api 로 접속하면 스웨거로 빠르게 접속할 수 있다.

 

ps. 자바스크립트 기반 프레임워크 같은 경우는,

swagger를 작성함에 있어 api에서 사용하는 인풋값의 타입을 직접 지정해주어야 하는 불편함이 있었는데,

스프링부트의 경우 아직까지는 그럴 필요가 없어서 꽤 만족스럽다.