[spring boot] swagger API 문서 자동화 하는 방법

이번 외주 프로젝트를 진행하면서 가장 먼저 진행했던 프로세스는 무엇이었냐면

aws 키를 받아 api 서버 오픈 준비를 하는 것이었다.

​

​

​

서버 오픈은 했지만 swagger 문서 ..? 이건 처음 들어봐서

swagger 가 뭔지 유튜브/ 블로그 등을 찾아보며 어떻게 하는건지 방법을 찾아봤다

​

​

Swagger 란?

Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트입니다. - About Swagger Specification

​

Swagger 를 왜 사용할까?

​

출처 : 어라운드 허브 스튜디오 유튜브

* API를 사용해 본 사람은 알겠지만 api 에는 정말 많은 정보가 담겨서 온다 !

그중에는 엄청 길고 비슷한 영어이름도 많아서 헷갈리는 경우도 많음

그래서 구글 스프레드 시트나 엑셀파일로

API 명세서를 작성했음

​

But! 이렇게 하게되면

​

* 서버 개발자가 명세서를 수정할 때마다

클라이언트 개발자 쪽에

api 명세서 최종, 찐최종, 진짜진짜최종

이런 사태가 발생하게됨

굉장히 불편하지 않겠음?

​

​

근데 Swagger 를 사용하면 프로젝트 파일에 코드 몇줄 추가해서

api 명세서를 만들면 되니

아주 개꿀 아니겠는가

거기다가 Postman 비슷한 테스트 할 수 있는 UI 까지 제공함

​

정리하자면

​

1. 코드 몇 줄 추가해서 깔끔한 API 명세서를 만들 수 있음

2. 문서 화면에서 API를 바로 테스트 할 수 있음

​

 

​

​

Swagger 사용 방법 - 1. 의존성 주입

​

​

​

​

​

​

맨 위에 springFox swagger2 랑

springFox swagger UI 이거 두개 maven , gradle 프로젝트에 맞춰서 의존성 추가해주면 된다!

버전은 2.9.2 많이 이용하는 듯

​

​

Spring boot 2.6 버전 이후는 swagger2와 충돌이 나므로 사용 X.

​

​

implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0' implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'

​

귀찮을 수 있으니 제가 드리겠습니다

dependencies 안에 추가 하고 코끼리 버튼 누르는거 다들 아시죠?

알거라 믿겠소

​

​

Swagger 사용 방법 - 2. Configuration

자 의존성 주입이 완료되었으니 이제 환경설정을 해봅시다

프로젝트 폴더 아래에 config 폴더를 만들고 다시 그 아래에 클래스를 하나 더 만들어 줍니다

​

​

환경 설정에 쓰이는 대표적인 어노테이션 2개는 다음과 같습니다 .

​

@Configuration

@Bean

​

​

​

@Configuration : 어노테이션 기반의 환경 구성을 돕는 어노테이션

IoC Container 에게 해당 클래스를 Bean 구성 Class 임을 알려줌

=> 즉 이 클래스에 Bean 이 있어! 하고 알려주는 용도다

​

@Bean: 개발자가 직접 제어가 불가능한 외부 라이브러리 등을 Bean으로 만들 경우에 사용

​

Spring IoC 컨테이너는 @Configuration 어노테이션이 적용된 클래스를 찾아 읽고, 내부의 @Bean 어노테이션이 적용된 메서드들을 호출하여 빈 객체로 등록합니다. 이렇게 등록된 빈 객체들은 스프링 애플리케이션 전반에서 사용되며, 스프링의 IoC 기능을 통해 의존성 주입이 이루어집니다. 이를 통해 개발자는 빈 객체들의 생성과 관리에 직접 신경쓰지 않고, 스프링이 관리해주므로 개발에 더욱 집중할 수 있습니다.

​

​

​

​

package com.lio.onkyeong.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket api(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) // API의 정보를 담고 있음 .select() .apis(RequestHandlerSelectors.basePackage("프로젝트 경로")) .paths(PathSelectors.any()) .build(); } public ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("Onkyung Frozen Warehouse Project Swagger") .description("설명 부분") .version("1.0.0") .build(); } }

위의 코드가 swagger 를 사용할 수 있도록 설정한 코드이다

한 줄씩 설명해보자면

​

​

@EnableSwagger2: Swagger를 사용하기 위한 어노테이션으로, 이를 선언함으로써 Swagger 관련 빈들이 활성화 됨

​

​

Docket: Swagger의 주요 빈으로, Swagger API 문서를 생성하고 API를 문서화하는 데 사용됨.

Docket 빈을 생성할 때 DocumentationType.SWAGGER_2(상수)를 지정하여 Swagger 2.0 버전을 사용하도록 설정​​

​

api()​메서드에서는 Docket 빈을 생성하고 구성을 정의함.

apiInfo()메서드를 호출하여 API의 정보를 설정

select()​메서드를 사용하여 어떤 API들을 문서화할지 선택.

ex) 프로젝트 경로가 com.demo 라면 com.demo 아래의 패키지들을 문서화 하는 것임

​

paths(PathSelectors.any())는 모든 경로를 문서화하도록 설정.

apiInfo() 메서드에서는 생성되는 API 문서의 정보 (문서의 제목, 설명, 버전 등)를 설정

​

​

swagger 접속

위의 작업을 모두 완료하고 자신이 설정한 포트번호로 요청을 보내주면

이런 화면이 뜬다!

(본인은 9090으로 설정함)

http://localhost:9090/swagger-ui/index.html

​

​

​

프로젝트 이름은 내가 지금하고 있는 외주가 냉동창고 웹사이트 만드는거라 ㅎㅎㅎㅎ

저렇게 설정되어 있다

​

​

​

​

엄청 간단한 컨트롤러 하나를 만들어주고 난 모습

이렇게 간단하게 api 명세서를 만들 수 있다니 협업할 때 아주 좋은 툴 같다