[swagger] 사용법

swagger 사용법 및 API 문서 자동화

 

Swagger 사용이유

- Spring으로 Rest API를 개발하고 그 API에 대한 문서를 정리하여 해당 API를 사용하는 클라이언트 및 서버 개발자들에게 문서를 정리해서 공유해야하는데 이때 Swagger를 이용하게되면 이런 작업을 보다 편리하게 할 수 있고 API 문서 자동화 뿐만 아니라 UI에서 직접 API 테스트로 할 수 있다.

 

Swagger 사용방법

- 어노테이션을 이용해서 원하는 설명을 적으면 된다. 주로 컨트롤러에 무슨 역할을 하는 컨트롤러인지, HTTP 메서드의 역할, 필요한 파라미터가 무엇인지, 파라미터 값 설명을 입력한다.  또한 schema 어노테이션을 사용하여 모델에 대한 추가 정보를 제공한다.

 

swagger 3 기타 annotation 참조:  https://jeonyoungho.github.io/posts/Open-API-3.0-Swagger-v3-%EC%83%81%EC%84%B8%EC%84%A4%EC%A0%95/

 

Dependency

API DOCs를 가능하게 해주는건 Springfox Swagger 와 SpringDoc 크게 두가지가 있는데 SpringDoc이 swagger3를 지원하여 채택.

 

• Controller

 

@Tag(name = “”, description = “”) 로 컨트롤러 이름 설정 및 명세 

@Operation(description =””)으로 HTTP 메서드 에대한 명세

@Parameter(description = “”)로 api 파라미터 리스트 표기 및 명세

 

 

•   Schema

 @schema -> Swagger 모델에 대한 추가정보를 제공

 

RequestBody와 ResponseBody를 설명할 수 있도록 도와주는것이 schema 이다.

description으로 설명을하고 example로 예시값을 넣는다.

 

 

 

•  ApiResponse

• responseCode: http 상태코드
• description: response에 대한 설명
• content: Response payload 구조

 

• schema: payload에서 이용하는 Schema

• hidden: Schema 숨김 여부
• implementation: Schema 대상 클래스
•  

@ApiResponse는 응답결과에 따른 response 구조를 미리 확인할 수 있게 해준다.

 

무늬뿐인 response 구조가 아닌, api 조회 성공 및 실패시 발생될 상태코드 및 Response 구조를 설정하고자 한다면 @ApiResponse를 설정하면 된다.

 

implementation 에 responseBody로 제공될 클래스의 Class 타입을 반환해야하는데, 이때 주의해야할 점은 implementation에는 class literal 타입만 들어갈 수 있다는 점이다.

 

 

기타 설정

 

-application.properties에서 설정

 

-springdoc.paths-to-match =/상대경로 

//보여주고싶은 컨트롤러만 보여주게 할 수 있다.

 

-springdoc.swagger-ui.operationsSrorter=alpha

//알파벳순서

 

-springdoc.swagger-ui.operations-sorter

//메서드 순서 delete - get - patch - post -put