스프링부트 Swagger UI 3.0.0 적용 방법 - 스프링부트 2.2 이상 (Spring Boot Swagger UI)

Spring Boot Swagger 3.0.0 적용하기 (스프링부트 2.2 이상 필요)

 

Swagger ?

간단히 말하자면 API 문서를 자동으로 만들어주는 라이브러리임 https://swagger.io/

예시는 스웨거의 Live Demo 참조 (https://petstore.swagger.io/)

완전 기본적인 적용방법에 대해서만 다룸.

 

• 단순 문서 뿐 아니라 API를 문서내에서 parameter를 넣어가며 바로바로 실행 해볼 수 있음.
  • rest api 제작 후 따로 테스트 페이지나 postman으로 실행해보는 대신 swagger 문서 만들어서 실행 가능.
  • 복잡하지 않은 시스템이라면 rest api 서버에 swagger를 적용시켜두고, 해당 api를 호출하는 작업자에게 뭐 복잡하게 설명하고 문서 만들 것 없이 swagger 문서 url만 보내서 알아서 작업하게 할 수 있음.

 

 

스프링부트에 Swagger 적용

1.

Gradle 추가

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

Maven 추가

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

 

2. 설정 클래스 (스프링 @Configuration 어노테이션 사용)

• '.basePackage()' 부분에 Swagger를 적용할 패키지 지정. 해당 패키지 이하의 모든 rest api가 자동으로 swagger 문서로 생성됨. (이하 예시에서는 'com.nahwasa.iot.controller' 패키지 이하를 모두 적용)

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder().title("IoT API")
                .description("IoT API Docs").build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.nahwasa.iot.controller"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
}

이 때, 해당 패키지 내에 포함되지만 Swagger 문서로 만들고 싶지 않을 경우 (예를들어 테스트용 컨트롤러나 api 작업자에게 보이기 싫은 api 등) 해당 컨트롤러에 @ApiIgnore 어노테이션을 추가하여 제외시킬 수 있음.

 

@Controller
@ApiIgnore
@RequestMapping("/")
public class IoTDevTestController extends IoTBaseController {
   ...

 

3. 문서상에 띄울 api별 설명 작성

 

@ApiOperation(value="AI 전기방식 동작여부 확인", notes="시스템에 등록된 현재 AI 전기방식 상태값 리턴(state:'Y' or 'N'). '../set-state'가 일정 시간 호출되지 않을 경우 N을 리턴.")
@ApiResponses({
        @ApiResponse(code = 200, message = "API 정상 작동"),
        @ApiResponse(code = 500, message = "서버 에러")
})
@RequestMapping(value="/is-running", method={RequestMethod.GET})
public ResponseEntity<AIRunningVo> isRunning() throws Exception {
    AIRunningVo res = new AIRunningVo();
    res.setState(AiStateManager.getInstance().getState());

    return new ResponseEntity<AIRunningVo>(res, HttpStatus.OK);
}

 

 

4. vo 내에 parameter 설명도 작성 가능함

@Data
public class AmiDeviceAddVo {
    @ApiModelProperty(value = "계량기번호", dataType = "string", required = true)
    String amiId;
    @ApiModelProperty(value = "검인일자")
    String bglnum;
    @ApiModelProperty(value = "고객센터")
    String ccenter;
	...
}

5. 기본 주소는 '/swagger-ui/index.html' 이지만 아래와 같이 redirect 등으로 변경하면 사용하기나 전달하기 좋음.

 

@Controller
@RequestMapping("/api/usage")
class SwaggerRedirector {
    @GetMapping
    public String api() { return "redirect:/swagger-ui/index.html"; }
}