TIL : Swagger 사용하기 (14)

📚 Swagger

Swagger란? API 명세서를 자동으로 작성해주는 라이브러리이다.

Swagger2, Swagger3이 있는데 버전이 다른 게 아니라 진짜 다른 라이브러리이다. (Spring Rest Doc)

1️⃣ 의존성 추가하기

implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

2️⃣ Configuration 추가하기

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /** http://localhost:8080/swagger-ui.html 에서 API 보기 */
    @Bean
    public Docket swagger() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.FlagHome.backend.v1"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("제목")
                .version("버전 1")
                .description("상세 설명")
                .build();
    }
}

• apis와 paths를 통해서 읽어들일 API를 제한할 수 있다.
• ApiInfo로 API Doc에 대한 정보를 적어줄 수 있다.

3️⃣ API 명세하기 feat.어노테이션

@RestController
@Api(tags = { "Swagger Test" })
//@ApiIgnore // 제외처리
public class SwaggerController {

    @ApiOperation(value = "Get 통신", notes = "Get 통신 Note", response = String.class)
    @ApiResponses(value = {
        @ApiResponse(code = 404, message = "페이지 없음"),
        @ApiResponse(code = 500, message = "서버 에러")
    })
    @GetMapping(value = "/swagger")
    public String GetRestApi(
        @ApiParam(value = "파라미터 1", required = true) @RequestParam(required = true, defaultValue = " ") String param1,
        @ApiParam(value = "파라미터 2", required = true) @RequestParam(required = true, defaultValue = "0") int    param2  ) {

        String result = "테스트";

        return result;
    }
}

• @Api : tag 옵션으로 Controller 명칭을 정해준다.
• @ApiIgnore : 해당 Controller를 제외한다.
• @ApiOperation : 해당 메서드에 대한 설명을 명세한다.
• @ApiResponses : Response 에러를 명세한다.
• @ApiParam : 파라미터에 대해 명세한다.

@ApiModel
public class User {
    @ApiModelProperty(value = "아이디", required = true)
    private String id;

    @ApiModelProperty(value = "패스워드", required = true)
    private String pw;
}

• @ApiModel : 해당 클래스가 API에 사용되는 클래스임을 명시해준다. 
• @ApiModelProperty : 변수에 대한 설명을 명세한다.