Spring Boot - Swagger

 

Swagger 란

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

 

Spring Boot에서는 간단하게 springfox-boot-starter를 gradle dependencies에 추가함으로 사용할 수 있다.

 

다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에는 사용할 땐 주의해야한다.

 

 

Swagger Annotation

 

 

Swagger 라이브러리 적용

maven repository에 접속해서 

springfox를 검색하여 swagger 관련 라이브러리를 찾을 수 있습니다.

https://mvnrepository.com/

 

예전에는 SpringFox Swagger2, SpringFox Swagger UI 라이브러리를 전부 의존성에 추가해서 사용했지만, 

SpringFox Boot Starter가 나온 이후에는 SpringFox Boot Starter 주로 사용합니다.

 

SpringFox Boot Starter 의존성 정보는 다음과 같습니다.

// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

 

gradle short 버전

implementation 'io.springfox:springfox-boot-starter:3.0.0'

 

의존성 추가하고 어플리케이션에 다른 설정이나 어노테이션을 지정할 필요가 없습니다.

자동으로 어플리케이션 전역에 Swagger가 적용됩니다.

 

swagger 실행방법

http://localhost:8080/swagger-ui/

브라우저에서 해당 url로 접속합니다.

주의할 점은 꼭 "/" url 맨뒤에 붙여주셔야합니다.

이제 문서화된 swagger ui를 확인하실 수 있을 것입니다!!

 

 

---

 

Swagger 예제

 

@Api

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

컨트롤러 클래스에 @Api 어노테이션을 붙인 뒤, @Api 어노테이션의 tags 속성에 컨트롤러의 이름이나 사용 용도를 표기합니다.

 

 

@ApiParam

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

    @GetMapping("/plus/{x}")
    public int plus(
	@ApiParam(value = "x값", required = false, defaultValue = "10")
	@PathVariable int x,
    
	@ApiParam(value = "y값", required = false, defaultValue = "20")
	@RequestParam int y) {

        return x + y;
    }
}

@ApiParam 어노테이션은 request 파라미터를 설명하는 어노테이션입니다.

value 속성에 파라미터의 이름을 기술하면 됩니다.

여담이지만, get 메소드에서 @ApiParam의 일부 속성이 정상적으로 작동하지 않는 것 같습니다.

required, defaultValue, example 등의 속성이 동작하지 않습니다.

(value와 hidden만 정상동작 확인)

 

 

@ApiImplicitParams과 @ApiImplicitParam

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

    @ApiImplicitParams({
        @ApiImplicitParam(name = "x", value = "x 값", dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "y", value = "y 값", dataType = "int", paramType = "query")
    })
    @GetMapping("/plus/{x}")
    public int plus(@PathVariable int x, @RequestParam int y) {

        return x + y;
    }
}

파라미터가 많으면 지저분해질 수 있는 @ApiParam 어노테이션을 대체할 수 있는 어노테이션이 있습니다.

@ApiImplicitParams과 @ApiImplicitParam 을 사용하면 파라미터의 swagger 설명을 보기 좋게 정리해서 코딩할 수 있습니다.

@ApiImplicitParam의 name 속성으로 파라미터 필드를 기술하고 value에는 파라미터 이름을 기술하면 됩니다. 

그외에 나머지 속성값은 옵션널이기 때문에 필요에 따라 사용하시면 됩니다.

 

 

@ApiOperation과 @ApiResponse

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

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

@ApiOperation 어노테이션은 해당 Controller 안의 method의 설명을 추가할 수 있습니다.

 

 

@ApiResponse 어노테이션은 해당 method의 Response에 대한 설명을 작성할 수 있습니다.

 

 

@ApiModelProperty

package com.example.swagger.dto;

import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserReq {

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

    @ApiModelProperty(value = "사용자의 나이", example = "10", required = false)
    private int age;

}

 

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

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

@ApiModelProperty 어노테이션은 DTO의 속성에 적용할 수 있습니다.

DTO의 각 속성들의 명칭, 필수값 여부를 지정할 수 있습니다.

 

@ApiModelProperty 어노테이션은 @ApiParam, @ApiImplicitParam 과는 다르게 필수값 여부가 정상적으로 적용됩니다.

참고로 get 메소드말고 post 메소드로 구현하면 request 파라미터에 @ApiModelProperty의 name과 required 속성은 적용되지 않습니다. 

반면 post 메소드에@ApiModelProperty의 example 속성은 적용됩니다.

 

 

@ApiIgnore

만일 API가 보이기 원치 않는 Controller에는 @ApiIgnore을 작성하면 Swagger에 보이지 않게 됩니다. 

Controller 클래스 위에 @ApiIgnore 어노테이션만 기술하면 적용됩니다.

 

 

 

 

https://velog.io/@gillog/Swagger-UI-Annotation-%EC%84%A4%EB%AA%85

[Swagger UI] Annotation 설명