20220715 TIL

Swagger

개발한 Rest API를 편리하게 문서화를 해주는 라이브러리. 관리자 및 제3 사용자가 편리하게 API를 호출해보고 테스트 할 수 있음

- 스프링뿐 아니라 파이썬 등으로 구성된 웹 프레임워크에서도 구성, 사용이 가능

- 스프링에서는 어노테이션 기반으로 우리가 만들어놓은 컨트롤러를 선택적으로 공개, 숨기는 기능이 가능

- 좀 더 어노테이션으로 디테일한 설명을 추가하는 것도 가능

 

Springboot에서 설정

Gradle Dependencies에 'springfox-boot-starter'를 추가하여 사용

1. Maven repository에 'Springfox Boot Starter' 검색. 오늘 기준으로 3.0.0 버전만 존재

2. Gradle에 해당하는 아래 코드를 복사 -> 프로젝트의 build.gradle의 dependency 부분에 붙여넣기

3. 잘 다운 받을 수 있게 gradle을 run 해주기

// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

4. Swagger 잘 적용되었는지 확인하기. /swagger-ui/ -> 끝의 '/'를 잊지 말자

localhost:[포트번호]/swagger-ui/

ex) localhost:8080/swagger-ui/

유의사항

운영환경과 같이 외부에 노출되면 안되는 곳에는 동작을 하지 않도록, 사용시 주의가 필요하다

내부 직원 끼리, 혹은 전체 공개인 api에 사용하는 것이 권장됨

 

Swagger에서 자주 사용되는 Annotation들

@Api : 클래스를 스웨거의 리소스로 표시

@ApiOperation : 특정 경로의 오퍼레이션 HTTP 메소드 설명

@ApiParam : 오퍼레이션 파라미터에 메타 데이터 설명

@ApiResponse : 오퍼레이션의 응답 지정

@ApiModelProperty : 모델의 속성 데이터를 설명

@ApiImplicitParam : 메소드 단위의 오퍼레이션 파라미터 설명

@ApiImplicitParams :