swagger 추가 및 사용예시

Swagger란?

API 문서화와 테스트를 위한 프레임워크

 

-  Swagger API 문서 생성 라이브러리 종류
1. springFox - 2020년 7월 이후로 업데이트 안되고 있음.
2. springDocs

 

의존성 추가( gradle 기준)

- springFox
implementation 'io.springfox:springfox-swagger-ui:3.0.0'
implementation 'io.springfox:springfox-swagger2:3.0.0'

또는

- springDocs
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
implementation 'org.springdoc:springdoc-openapi-ui:1.8.0'

 

- springDocs 라이브러리를 이용해서 구축

1. SwaggerConfig 클래스 생성

OpenAPI: API 문서의 메타데이터를 정의하는데 사용되는 객체
Info: OpenAPI 사양에서 API의 기본 정보를 제공하는 객체. 이 객체는 API 문서의 제목, 설명, 버전 등을 설정하는 데 사용

 

 

2. application.properties 또는 application.yml에 swagger관련 설정 추가

springdoc.api-docs.enabled: swagger api 문서 활성화
springdoc.swagger-ui.enabled: swagger UI 페이지 활성화
springdoc.swagger-ui.path= swagger UI 엔드포인트 설정
springdoc.api-docs.path= swagger api 문서 엔드포인트 설정
springdoc.api-docs.groups.enabled=true: api 문서 그룹화 설정
ex> /v3/api-docs/{그룹1}, /v3/api-docs/{그룹2} 형식으로 요청 시 그룹별로 api 문서를 보여줌

** 엔드포인트란
소프트웨어 시스템, 특히 웹 서비스나 API에서 특정 기능이나 데이터를 제공하는 URL 또는 URI

 

3. annotation을 활용해 코드 작성

- 만약 기존 springFox를 사용한 프로젝트에서 Migration시 설정파일 외 코드도 수정필요하며 관련된 내용은 공식 홈페이지에 예시와 함께 나와있다.

https://springdoc.org/#migrating-from-springfox

OpenAPI 3 Library for spring-boot

 

 

4. 결과 확인

 

 

5. 기타
- swagger 2 annotation과 swagger 3 annotation 비교

Swagger 3 (OpenAPI 3.0)	Swagger 2 (Swagger 2.0)	설명
@Tag	@Api	클래스를 Swagger 리소스로 표시
@Parameter(hidden = true) @Operation(hidden = true) @Hidden	@ApiIgnore	API 작업에서 단일 매개 변수를 숨김
@Parameter	@ApiImplicitParam	API 작업에서 단일 매개 변수를 나타냄
@Parameters	@ApiImplicitParams	API 작업에서 복수 매개 변수를 나타냄
@Schema	@ApiModel	Swagger 모델에 대한 추가 정보를 제공
@Schema(accessMode = READ_ONLY)	@ApiModelProperty(hidden = true)	모델 속성의 데이터를 추가하고 조작
@Schema	@ApiModelProperty	Swagger 모델에 대한 추가 정보를 제공
@Operation(summary = "foo", description = "bar")	@ApiOperation(value = "foo", notes = "bar")	특정 경로에 대한 작업 또는 일반적으로 HTTP 메서드를 설명
@Parameter	@ApiParam	작업 매개 변수에 대한 추가 메타 데이터를 추가
@ApiResponse(responseCode = "404", description = "foo")	@ApiResponse(code = 404, message = "foo")	작업의 가능한 응답을 설명

 

-Springdoc-openapi Properties

속성	설명	기본값
springdoc.api-docs.enabled`	OpenAPI API 문서화 활성화 여부	true
springdoc.api-docs.path	API 문서의 URL 경로	/v3/api-docs
springdoc.api-docs.title	API 문서의 제목	없음
springdoc.api-docs.description	API 문서의 설명	없음
springdoc.api-docs.version	API 문서의 버전	없음
springdoc.api-docs.default-group-name	기본 API 그룹 이름	default
springdoc.api-docs.groups.enabled	API 문서의 그룹화 기능 활성화 여부	true
springdoc.api-docs.groups	API 문서의 그룹 설정 (Comma-separated list of group names)	없음

 

- Swagger-ui properties

속성	설명	기본값
springdoc.swagger-ui.enabled	Swagger UI 활성화 여부	true
springdoc.swagger-ui.path	Swagger UI의 URL 경로	/swagger-ui.html
springdoc.swagger-ui.configUrl	Swagger UI에서 사용할 OpenAPI 문서의 URL	/v3/api-docs

 

 

**참고자료
https://springdoc.org/#features