728x90
💡 Swagger 란?
자신이 개발한 REST API를 편리하게 문서화 해주고, 이를 통해서 관리 및 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트이다.
(운영환경과 같은 외부에 노출되면 안되는 곳에서 사용 시에는 주의 필요.)
gradle의 dependencies{}에 추가
// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
Ex >
웹에 http://localhost:8080/swagger-ui/ 주소로 검색하여 확인
@Api(tags = {"API 정보를 제공하는 Controller"})
@RestController
@RequestMapping("/api")
public class ApiController {
@ApiImplicitParams({
@ApiImplicitParam(name = "x", value = "x 값", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "y", value = "y 값", required = true, dataType = "int", paramType = "query")
})
@GetMapping("/plus/{x}")
public int plus(@PathVariable int x, @RequestParam int y) {
return x+y;
}
@ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
@ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메소드")
@PostMapping("/user")
public UserRes userPost(@RequestBody UserReq req) {
return new UserRes(req.getName(), req.getAge());
}
}
Swagger Annotation
@Api
- 클래스를 스웨거의 리소스로 표시
@ApiOperation
- 특정 경로의 오퍼레이션 HTTP 메서드 설명
@ApiParam
- 오퍼레이션 파라미터에 메타 데이터 설명
@ApiResponse
- 오퍼레이션의 응답 지정
@ApiModelProperty
- 모델의 속성 데이터를 설명
@ApiImplicitParam
- 메서드 단위의 오퍼레이션 파라미터를 설명
@ApiImplicitParams
- 메서드 단위의 오퍼레이션 파라미터들을 설명
💡 Swagger 적용 시 Plugin실행 에러
Spring boot 2.6버전 이후에 spring.mvc.pathmatch.matching-strategy 값이 ant_apth_matcher에서 path_pattern_parser로 변경되면서 몇몇 라이브러리(swagger포함)에 오류가 발생한다고 한다.
해결 방법
src → main → resources → application.properties 파일에 ‘spring.mvc.pathmatch.matching-strategy = *ANT_PATH_MATCHER*’ 추가하면 된다.
728x90