Swagger

1. Swagger ?

  > REST API를 설계, 구축, 문서화 및 사용하는데 도움이 될 수 있는 Open API Specification 기반 오픈 소스 도구 모음

  > Springboot에 Swagger 적용 시 컨트롤러에 명시된 어노테이션을 기반으로 API문서를 자동으로 만들어준다.

 

2. Swagger 설정

---

Project

  1) pom.xml

---

  <!-- Swagger2 -->
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
  </dependency>

  <!-- Swagger UI -->
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
  </dependency>

---

  2) SwaggerConfig.java

    > Springfox 참조 문서 

---

package com.spring.swagger.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket SwaggerApi() {
    String apiName = "SwaggerApi";
    String apiVersion = "v1";
    String apiDescription = String.format("Documentation %s %s", apiName, apiVersion);

    return new Docket(DocumentationType.SWAGGER_2)
          .groupName(apiName)
          // Swagger API Docs Description
          .apiInfo(
              new ApiInfoBuilder()
                    .version(apiVersion)
                    .title(apiName)
                    .description(apiDescription)
                    .build()
          )
          // select() : ApiSelectorBuilder 인스턴스 반환하여 swagger를 통한 endpoints 제어
          .select()
          // Swagger API 문서로 만들기 위한 Base Package
          .apis(RequestHandlerSelectors.basePackage("com.spring.swagger.controller"))

          .paths(PathSelectors.regex(".*?"))
          .build();
  }
}

---

  3) IndexController.java

---

package com.spring.swagger.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.annotations.ApiIgnore;

/**
* Swagger Document Page로 Redirect 해주는 Controller
* ApiIgnore > Swagger API 리스트에는 보이지 않게 한다.
* */
@Controller
@RequestMapping("/")
public class IndexController {
  @ApiIgnore
  @GetMapping("/")
  public String index() {
    return "redirect:" + "/swagger-ui.html";
  }
}

---

  4) SwaggerController.java

---

package com.spring.swagger.controller;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.time.LocalDate;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/v1")
public class SwaggerController {

  @ApiOperation(value="API Title", notes="API Description")
  @ApiImplicitParams({
         @ApiImplicitParam(name = "apiParameter", dataType = "string", paramType = "query", example = "Swagger"),
         @ApiImplicitParam(name = "swaggerYn", dataType = "string", paramType = "query", example = "Y", allowEmptyValue = true, allowableValues = "Y, N")
  })
  @GetMapping(value = "/Swagger")
  public ResponseEntity getSwagger(@RequestParam String apiParameter

                                              , @RequestParam(required = true) String swaggerYn){
    String str = "Hello! ";
    str += apiParameter;
    str += "\n SwaggerYn is ";
    str += swaggerYn;
    return ResponseEntity.ok(str);
  }

  @ApiOperation(value = "This method is used to get the current date.", hidden = false)
  @GetMapping("/getDate")
  public LocalDate getDate() {
    return LocalDate.now();
  }

  @ApiOperation(value = "PostMapping", hidden = false)
  @PostMapping("/post")
  public ResponseEntity postData() {
    /* Business Logic */
    return ResponseEntity.ok("Y");
  }

  @ApiOperation(value = "PutMapping", hidden = false)
  @PutMapping("/put")
  public ResponseEntity putData() {
    /* Business Logic */
    return ResponseEntity.ok("Y");
  }

  @ApiOperation(value = "DeleteMapping", hidden = false)
  @DeleteMapping("/post")
  public ResponseEntity deleteData() {
    /* Business Logic */
    return ResponseEntity.ok("Y");
  }
}

---

Swagger UI

[Try it out]

Parameter 지정 후 API [Execute]

Response

---

3. Annotations

  > Swagger API Documentation

  > https://github.com/swagger-api/swagger-core/wiki/Annotations

Annotation	Description
@Api	클래스를 Swagger 리소스로 표시하는 어노테이션. Swagger-Core는 @Api 어노테이션이 붙은 클래스만 포함하고 검사한다. 다른 리소스는 무시한다.
@ApiImplicitParam	단일 매개변수.
@ApiImplicitParams	다수의 ApiImplicitParam 오브젝트 목록을 허용하는 wrapper이다.
@ApiModel	Swagger 모델에 대한 추가 정보 제공. 자동으로 내부 검사되지만, 모델의 구조를 조작할 수 있다.
@ApiModelProperty	모델 속성의 데이터를 추가하고 조작한다.
@ApiOperation	특정 경로에 대한 작업 또는 일반적으로 HTTP 메서드를 설명한다.
@ApiParam	매개변수의 메타데이터(속성정보) 추가한다.
@ApiResponse	작업의 가능한 응답을 설명한다. REST API 호출로부터 가능한 성공 및 에러 코드를 설명하는데 사용할 수 있다.
@ApiResponses	다수의 ApiResponse 오브젝트 목록을 허용하는 wrapper이다. 단일 ApiResponse 사용 시에도 해당 어노테이션을 사용하고 @ApiResponse을 배열로 래핑해야 한다.
@ApiIgnore	파라미터/작업을 숨김처리 한다.