Spring boot Swagger 사용하기

Summry

본 문서에서는 spring boot에 swagger를 적용하는 방법을 정리한다.

send me email if you have any questions.

Swagger 적용

1. dependency 찾기

mvnrepository에 들어가서 원하는 버전의 dependency를 찾는다.

본 문서에서는 가장 많이 사용된 2.9.2버전을 기준으로 한다.

2. dependency 적용

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

build.gradle에 의존성을 추가한다.

swagger2도 추가해준다.

3. SwaggerConfig 생성

package com.thinkingcode.homepage.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.thinkingcode.homepage"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("API")
                .description("API")
                .version("1.0")
                .build();
    }
}

SwaggerConfig.java

주요 옵션
- apis : 대상 패키지 설정
- paths : 어떤 식으로 시작하는 api 를 보여줄것인지 지정
  - any는 그냥 전부다. 만약, member/ 라고 설정하면 member로 시작하는 api 만 볼 수 있게 설정 가능하다.

4. web page 접속

Swagger의 기본 uri는 swagger-ui.hmtl이다.

ex) http://locathost:8080/swagger-ui.html

Swagger Annotation

@ApiOperation

@ApiOperation을 사용하면 해당 Controller 안의 method의 설명을 추가할 수 있다.

@PostMapping("/schedule")
  @ApiOperation(value = "일정 추가 API", notes = "신규 일정 추가 API\nconfirm의 default 값은 false이며 idx는 auto_increment.")
  public int post_schedules(@RequestBody calendarTable carendarParm, HttpServletResponse res) {
    ...
    ...
    }
  }

example

그림1

@ApiImplicitParam

@ApiImplicitParam을 사용하여 해당 API Method 호출에 필요한 Parameter들의 설명을 추가할 수 있다.

  @DeleteMapping("/schedule")
  @ApiOperation(value = "일정 삭제 API", notes = "일정을 삭제하는 API로 해당 일정의 index를 querystring으로 요구함.")
  @ApiImplicitParam(
    name = "idx"
    , value = "index"
    , required = true
    , dataType = "string"
    , paramType = "path"
    , defaultValue = "None")
  public int delete_schedules(@RequestParam(value = "idx") String qureystring, HttpServletResponse res) {
    ...
    ...
  }

example

dataType, paramType, required의 경우 해당 name의 정보가 자동으로 채워지므로 생략 할 수 있다.
paramType의 경우 @RequestParam은 query를, @PathVariable은 path를 명시해주면 된다.
만약 해당 Method의 Parameter가 복수일 경우, @ApiImplictParams로 @ApiImplictParam을 복수개 사용할 수 있다.

그림2

@ApiModelProperty

@ApiModelProperty를 DTO Class Field에 추가하면, 해당 DTO Field의 예제 Data를 추가할 수 있다.

public class schedule {
    @ApiModelProperty(notes = "일정 index")
    private String idx;

    @ApiModelProperty(notes = "일정 제목")
    private String header;

    @ApiModelProperty(notes = "일정 마감 날짜")
    private String deadline;

    @ApiModelProperty(notes = "신규 일정 착수 가능 날짜")
    private String empty_schedule;

    @ApiModelProperty(notes = "일정 완료 여부")
    private String confirm;
}

example

그림3

Reference

Spring boot Swagger 설정 (gradle) 🐏 - borab
[Swagger UI] Annotation 설명 - gillog

PREVIOUSmybatis 비교연산자 에러

NEXTspring boot CORS 처리