Swagger
과거 : 문서를 통한 Backend <-> FrontEnd 정보 교환
단점
- FrontEnd는 문서를 보고 이해하는 일
- Backend는 문서를 만드는 일
- 문서를 수정해야하는 일이 생길 때
Swagger
- 기존 문서로 사용하던 문제를 해결하기 위해 Swagger 사용
- 간단한 설정으로 프로젝트의 API 목록을 웹에서 확인 및 테스트 할 수 있게 해주는 Library
- Swagger를 사용하면 Controller에 정의되어 있ㄴ는 모든 URL을 바로 확인할 수 있다.
- API 목록 뿐 아니라, API의 명세 및 설명도 볼 수 있으며, 또한 API를 직접 테스트해 볼 수 있다.
- 명세 : 사용자의 endPoint (@RequestMapping)
Swagger 적용 방법
mvn Repository -> springfox 등록
swagger-ui/index.html 로 접속하면 swagger 확인 가능
에러 발생시,
Swagger - 3.0 버전이랑 boot 2.6 이상 버전과 충돌로 에러 발생
-> boot 2.4 버전으로 바꾸기 (대안)
-> resource-handler를 통해서 읽지못하는 url을 직접 등록해주면 해결 가능
@Configuration : Spring에서 Servlet-context, Root-context 등의 설정 파일을 해당 지정하고자 하는 클래스가 대체하겠다.
자 실제로 이제, boardController를 통해 swagger api를 사용해 보자
사전 준비 Anotation
- @RestControlloer
- @RequestMapping("/api")
Swagger Annotation
| Annotation | Description |
|---|---|
| @api | Controller가 Rest 방식을 처리하기 위한 것임을 명시 |
| @ApiIgnore | Class, Method에 선언이 가능하며 클라이언트에 노출하고 싶지 않은 경우 |
| @ApiOperation | 제공되는 API에 대한 간단한 설명 (메서드 설명) |
| @ApiModel | URL 경로에 있는 값을 파라미터로 추출 (Dto class) |
| @ApiModelProperty | 결과로 응답되는 데이터 필드에 대한 설명 (Dto의 멤버) |
| @ApiImplicitParam | API 요청시 설정되는 파라미터에 대한 설명 |
| @ApiImplicitParams | API 요청 시 설정하는 파라미터가 여러개일 경우 ApiImplicitParam과 함께 사용 |
@ApiParam은 직접 함수의 파라미터에 Annotation을 설정하는 방식이라면
@ApiImplicitParams는 따로 paramter에 대한 설명들을 전부 빼서 나타내기 때문에 가독성 측면에서 선호된다.
ApiImplicitParams가 큰 틀이고, 그 안에 ApiImplicitParam( == ApiParam 이랑 같은 역할)을 채워줘 완성한다.
@ApiModel data - schima를 정의하는데에 사용된다. 주로 DTO를 표현할 때 사용
@ApiModelProperty : ApiModel 내, 멤버 변수에 대해서 정리할 때 사용한다.
swagger의 장점: 단순히 문서화만 시켜주는 것이 아니라,
정해진 format에 맞춰 데이터를 입력할 경우, 그에 맞춰 메소드가 반환해주는 결과 값도 알려준다.
기타 swagger의 문서화 된 부분을 변경 / 조작 하고자 할 때
- swagger는 설정 정보를 가지고 있는 bean class를 탐색
- 이 때 해당 bean class는 Docket 타입이어야 한다.
select() // selector 선언
apis(RequestHandlerSelectors.basePackage("com.ssafy.swagger.controller")) // 어느 패키지를 담을지
paths(PathSelectors.ant("/api/**")) // 어느 경로로 들어오는 값을 받을지
.build() // 여기까지만 해도 작동함
.apiInfo(apiInfo()); // swagger description에 대한 내용을 ApiInfo type의 class apiInfo로 받아서 사용
