[Spring Boot] API Docs를 자동으로 만들어보자!

 

많은 분들이 그렇겠지만 저는 지금까지 FE 팀원들과 소통하기 위해서
Notion에 API Docs를 만들어서 사용했습니다.

이렇게 만들면 귀찮아서 하기 싫고...
코드에 수정이 발생하면 이것도 수정해야하고...
오타 검수도 힘들고....

너무 불편해서 찾아봤더니 Swagger라는 툴을 주로 사용한다고 해서
저도! 사용해보고자 합니다. ㅎㅎ

 

왜 Swagger?

다른 문서화 도구도 있지만 Swagger는 특히 적용하기 쉽습니다!
정말 몇 줄의 코드만으로 만들 수 있어요!

그리고 테스트를 할 수 있는 UI를 제공해줘서
Swagger 문서 화면에서 API를 바로 테스트할 수도 있습니다!

저는 지금까지 Postman을 사용해서 API를 테스트했는데,
Postman에서 API를 문서화하면... Notion이랑 다를게 없더라구요...

 

그래서 저는 쉬운 자동화와 API 테스트 모두를 경험해볼 수 있는 Swagger를 선택했어요.

버전은 사람들이 많이 사용하는 버전으로 선택했어요.
(2.9.2를 주로 사용 하시더라구요!)

 

Swagger 2 사용

의존성을 추가해주고

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

 

클래스를 하나 만들어서 설정을 정의해줍니다.  ( yaml 파일로 하는 방법도 있어요! )

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket apiV1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.api"))
                .paths(PathSelectors.any())
                .build();
    }
}

더 추가된 설정들이 있지만, 기본적으로는 이정도만 있어도 됩니다!

• apis()
  basepackage에 본인의 컨트롤러들을 모아둔 패키지를 입력하여 지정해줍니다!
• paths()
  apis()로 선택된 API 중에서 특정 path를 필터링해서 문서화할 수 있게 해줍니다.
  /user 로 시작하는 API만 필터링해서 문서화 한다면 PathSelectors.ant("/user/**")
  전부 다 하려고 한다면 위와 같이 하면 됩니다

이렇게 만들어서 실행시켜준 후
http://localhost:8080/swagger-ui.html  로 접속해주면!!

와 쉽다.. 이러면 자동으로 문서를....

 

엥?? 위기...

분명 찾아본 블로그에서 하라는대로 했는데 계속 오류가 뜨더라고요..

 

Error creating bean with name 'apiDocumentationScanner' defined in URL

처음에는 빌드 과정에서 이런 오류가 떴어요..
이 오류는 Configuration 어노테이션이 spring context 관련된 설정과 중복되어 발생한다고 해서 주석처리를 해줬더니

 

하라는대로 했는데!!

이번에는 이렇게 오류가 떠서 찾아보니 스웨거 빈을 생성하지 않아서 나온 에러라고 말씀하시면서
제 스프링 버전과 충동 오류가 있다고 하네요

 

Spring Boot 버전이 2.6 이상이라면 Swagger 2.x.x가 아닌 3.x.x을 사용해야 합니다!
또한, Springfox보다 Springdoc-openapi를 사용하는 것을 추천합니다.
Springfox는 더 이상 업데이트가 되지 않아요!

 

Swagger 3

의존성을 먼저 바꿔주고 실행해봅시다.  ( 자세한 설정 방법은 밑에 참고한 게시글을 남겨두겠습니다 )

    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

 

스프링을 실행시키고

http://localhost:8080/swagger-ui/index.html    이 곳으로 접속하면 !

아이 편하다~~

 

Reference

https://velog.io/@banjjoknim/Swagger
https://hjh0827.tistory.com/96
https://gomgomkim.tistory.com/55
https://colabear754.tistory.com/99
https://tecoble.techcourse.co.kr/post/2020-08-31-spring-swagger/

 

 

 

기존과는 다르게 편하게 말하듯이 작성해봤는데,
부담감이 약간 줄어들면서 작성하기 편하긴 하네요 ㅎㅎ..