[Fast Campus] 한번에 끝내는 Java/Spring : Swagger를 통한 API 공개

✨ Swagger란

Swagger

개발한 REST API를 편리하게 문서화 해주고, 이를 통해서 관리 및 제3의 사용자가 편리하게 API를 호출하고 테스트 할 수 있는 프로젝트

• Spring Boot에서는 간단하게 springfox-boot-starter 를 gradle dependencies 에 추가함으로 사용 가능
• 운영환경과 같은 외부에 노출되면 안되는 곳에서는 사용할 때 주의

✨ Swagger 설정하기

MVN Repository

• Springfox Boot Starter >> 3.0.0 : dependency 추가
• localhost:8080/swagger-ui/ : 접속(끝에 / 붙여야함)

Swagger Annotation

@Api

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

@ApiOperation

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

@ApiParam

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

@ApiResponse

오퍼레이션의 응답 지정

@ApiModelProperty

모델의 속성 데이터를 설명

@ApiImplicitParam

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

@Api

@Api(tags = {"API 정보를 제공하는 Controller"})
public class ApiController{

• 클래스위에 붙임, 클래스에 대한 설명

@ApiParam

public int plus(@ApiParam(value = "x값") @PathVariable int x, @ApiParam(value = "y값") @PathVariable int y){

• @PathVariable 위에 붙임, 파라미터에 대한 설명

@ApiModelProperty

@ApiModelProperty(value = "사용자의 이름", example = "steve", required = true)
private String name;

• Dto 에 붙임, Dto의 속성에 대한 설명

@ApiResponse & @ApiOperation

@ApiResponse(code = 502, message = "사용자의 나이가 10살 이하일때")
@ApiOperation(value = "사용자의 이름과 나이를 리턴하는 메서드")
@GetMapping("/user")
public UserRes user(UserReq userReq){

• 에러코드에 따라서 추가 설명
• 메서드에 따른 추가 설명

@ApiImplicitParam

@ApiImplicitParams({
	@ApiImplicitParams(name = "x", value = "x 값", required = true, dataType = "int", paramType = "path"),
	@ApiImplicitParams(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;
}

• name 에 설정된 이름과 함수 인자의 이름과 동일하게 설정
• @ApiParam 보다 많은 param을 설명하는 것에 대해 적합

---

📝 마치며

API를 테스트할 때, 용이한 방법이라고 생각했다. 또한 다른 누군가에게 API를 설명할 때, 문서를 대체할만큼 설명에 대한 도움을 얻을 수 있을 것 같다.