Swagger
Swagger 무엇일까 알아보자
Swagger
Swagger란 개발한 REST API 를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다. Spring 뿐만아니라 다른 프레임워크에서도 설정할 수 있다.
Spring Boot에서는 간단하게 springfox-boot-starter를 gradle dependencies에 추가 함으로 사용할 수 있다.
다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에는 사용할 땐 주의 해야한다.
Swagger Annotation
- @Api : 클래스를 스웨거의 리소스로 표시
- @ApiOperation : 특정 경로의 오퍼레이션 HTTP메소드 설명
- @ApiParam: 오퍼레이션 파라미터에 메타 데이터 설명
- @ApiResponse : 오퍼레이션의 응답 지정
- @ApiModelProperty: 모델의 속성 데이터를 설명
- @ApiImplicitParam : 메소드 단위의 오퍼레이션 파라미터를 설명
- @ApiImplicitParams
Spring boot에 Swagger 적용해보기
build.gradle에
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
해당 코드를 추가를 했다.
이렇게 하고 Api-controller를 테스트로 세팅을 하고 run을 돌려봤더니 오류가 발생하였는데 검색을 해보니 SpringBoot 2.6 이상 springfox-swagger3.0 적용 시 에러가 발생한다는 이슈가 있었다.
해결방법으로는
1. application.properties 수정
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
으로 defualt값을 수정하기
2. spring boot의 버전을 낮추기
였다. 나는 1번으로 수정을 하였고
http://localhost:8080/swagger-ui/를 통해 Swagger와 연동을 테스트를 진행 해 보았다.
@Api : 클래스를 스웨거의 리소스로 표시
이렇게 태그를 이용해 Swagger에 보이는 리소스 를 수정할 수 있다.
@ApiParam: 오퍼레이션 파라미터에 메타 데이터 설명
실행결과 이렇게 무슨값인지 모르겠는 설명이 나온다 메타 데이터에 대한 설명을 추가하기 위해서
@GetMapping("/plus/{x}")
public int plus(
@ApiParam(value = "x값")
@PathVariable int x,
@ApiParam(value = "y값")
@RequestParam int y) {
return x + y;
}변경후 실행 결과
* @ApiModelProperty: 모델의 속성 데이터를 설명
@GetMapping("/user")
private UserRes user(UserReq userReq) {
return new UserRes(userReq.getName(), userReq.getAge());
}이렇게 객체(Object)를 반환할때는 Object에 세팅을 해주면 가능하다
@ApiModelProperty(value = "사용자의 이름",example = "steve",required = true)
private String name;
@ApiModelProperty(value = "사용자의 나이",example = "10",required = true)
private int age;애노테이션을 사용해 설명을 추가하면
이렇게 확인 할 수 있다.
* @ApiOperation : 특정 경로의 오퍼레이션 HTTP메소드 설명
@ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메소드")
해당 메소드위에 이렇게 애노테이션을 추가하면 해당 메소드에 대한 설명을 추가 할 수 있다.
