[spring boot] OpenApi를 사용하여 Rest api 문서화

springdoc-openapi java 라이브러리는 스프링 부트 프로젝트를 사용하여 API 문서 생성을 자동화 하는 역할을 합니다.

springdoc-openapi 스프링 구성, 클래스 구조 및 다양한 주석을 기반으로 API 의미를 추론하기 위해 런타임에 애플리케이션을 검사하여 작동합니다.

더 자세한 내용은 아래 링크에서 확인 가능합니다.
https://springdoc.org/

사용방법

spring boot version : 3 는 springdoc-openapi v2를 사용해야 합니다.

spring boot version : 2.7.11

build.gradle

dependencies {
	implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'
}

spring boot와 swagger-ui 간의 통합을 위해 라이브러리를 프로젝트 종속성 목록에 추가합니다.(추가 구성이 필요하지 않습니다.)
이렇게 하면 swagger-ui가 자동으로 spring boot 애플리케이션에 배포됩니다.

application.yml

springdoc:
  swagger-ui:
    path: /doc.html

이제 프로젝트를 실행시키고 localhost:8080/doc.html로 접속해보겠습니다.

정말 간단한 방법으로 문서화가 완료되었습니다.

api 테스트도 진행해 볼 수 있습니다.

하지만 아쉬운 점은 api에 대한 설명이 부족하다는 것입니다. 설명을 추가해보도록 하겠습니다.

@Configuration
public class SpringDocConfig {

    public static final String API_PATH = "/api/**";

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .addServersItem(new Server().url("/"));
    }

    @Bean
    public GroupedOpenApi deviceAPI() {
        return GroupedOpenApi.builder()
                .group("01. 디바이스 API")
                .pathsToMatch(API_PATH)
                .packagesToScan("com.swaggerTest.device.restcontroller")
                .build();
    }
}

config 파일을 하나 만들어서 다음과 같이 설정을 하였습니다.

그리고 com.swaggerTest.device.restcontroller 패키지 안에 있는 RestController 위에 @Tag 어노테이션을 추가해줍니다.

@Tag(name = "01. 디바이스 API", description = "디바이스 관련 API")
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api")
public class commandController {
	// ..function 생략
}

다시 프로젝트를 실행 시키고 localhost:8080/doc.html을 확인해보겠습니다.

이제 어떤 api인지 설명이 추가된 것을 볼 수 있습니다.

간단한 rest api 문서화에 대해서 알아보았습니다.

참조
https://springdoc.org/