Swagger 를 적용한 API 문서 자동화

API에 따른 요청/응답을 자동으로 문서화해주는 툴에 대해 알아보자 !

API 문서 자동화 툴

API 명세에 대한 문서 자동화 툴은 대표적으로 Spring REST Docs 와 Swagger 가 있다.

• Spring Rest Docs 는 Spring 기반의 RESTful API를 문서화하기 위한 도구로, 테스트 기반의 접근 방식을 사용하여 API 문서를 생성한다.
• Swagger 는 API 개발 및 문서화를 위한 오픈 소스 프레임워크로, RESTful 웹 서비스를 설계, 빌드, 문서화하는 데 도움을 주는 툴이다.
  
  

이 중 나는 Swagger 를 선택하여 API 문서를 자동화 하였다. Spring Rest Docs 말고 Swagger 를 선택한 이유는 다음과 같다.

• Spring Rest Docs 는 테스트 기반의 문서로 작성되므로 API 와 항상 일치하는 문서를 작성할 수 있지만, 테스트가 실패하면 문서도 생성되지 않는다.
• 캡스톤은 소규모 프로젝트이기 때문에 API 동작을 확인하는 것이 더 우선적이다.

Swagger 적용

※ Springboot 2.6.0 에서 진행

build.gradle

아래와 같이 swagger 의존성을 추가한다.

// Swagger
implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'

application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    groups-order: desc
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json

SwaggerConfig

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .version("v1.0.0")
                .title("Muse API")
                .description("Muse API 명세서입니다.");

        return new OpenAPI().info(info);
    }
}

※ title 과 description 은 자신의 프로젝트에 맞는 내용을 작성하면 된다.

WebSecurityConfig

Security 를 사용하지 않을 경우, 이 설정은 넘어가도 된다.

@Configuration
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    public void configure(WebSecurity web) throws Exception {
        web
        	.ignoring()
            .antMatchers("/api-docs", "/swagger*/**");
    }

위 3가지의 설정이 끝나면 Swagger 의 모든 설정은 끝났다.

가독성 있는 문서를 만들고 싶다면 컨트롤러 단에 아래 어노테이션을 추가하면 된다.

• @Tag : API 그룹의 이름

@Tag(name = "채팅방 API")
public class ChatRoomController { ... }

• @Operation : API 별 정보 설명

@Operation(summary = "채팅방 생성")
@PostMapping("/room")
public MessageResponseDto createChatRoom() { ... }

잘 적용되었는지 확인해보자 !

애플리케이션을 실행하고 http://localhost:8080/swagger-ui/index.html 에 접속하면 된다.