Swagger를 통해 REST API로 개발한 내용의 문서화가 가능하며, 간단한 테스팅 작업을 UI로 표현 가능하기 때문에 사용했습니다. Shoooooooot!

설정

build.gradle

dependencies {
		//swagger
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

• 스프링의 gradle에 의존성을 추가하여 swagger를 사용할 수 있도록 합니다.

SwaggerConfig.class

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String API_NAME = "JinMin's Board";
    private static final String API_VERSION = "0.1";
    private static final String API_DESCRIPTION = "Board 명세서";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("me.jinmin.boardver2"))
                .paths(PathSelectors.any())
                .build();
    }

    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;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }
}

• @Configuration : 설정 파일을 가르키는 스프링 애노테이션입니다. 이를 통해, 스프링 빈 컨테이너에서 해당 클래스를 설정 클래스로 간주합니다.
• @EnableSwagger2 : Swagger를 사용할 수 있도록 하는 애노테이션입니다.
• Docket 클래스를 빌더 형식으로 구현한 후 반환합니다. (설정 메서드들에 대해 간략히 설명하겠습니다!)

  참조 사이트 : https://springfox.github.io/springfox/javadoc/current/springfox/documentation/spring/web/plugins/Docket.html

  • consumes : Set, 요청 타입을 설정할 수 있습니다.
  • poduces : Set, 응답 타입을 설정할 수 있습니다.
  • apiInfo : ApiInfo, swagger ui에서 보여지는 간략한 정보를 입력할 수 있습니다.
  • userDefaultResponseMessages : false로 설정할 경우 자동적으로 status code를 생성합니다.
  • select : ApiSelectorBuilder 생성
    • apis : 패키지 위치를 지정합니다.
      • RequestHandlerSelectors.basePakage : 요청 기본 패키지를 지젛압니다.
    • paths : 경로를 지정합니다.
      • PathSelectors.any : 어느 경로도 선택될 수 있습니다.

예제

• UserSignApi

  @Slf4j
  @RestController
  @RequiredArgsConstructor
  @RequestMapping("/users")
  public class UserSignApi {
  
      private final UserSignService userSignService;
  
      @ApiOperation(value = "회원가입", notes = "회원가입을 합니다.")
      @ApiResponses({
              @ApiResponse(code = 200, message = "success"),
              @ApiResponse(code = 404, message = "Not found")
      })
      @PostMapping("/signup")
      public ApiResult<Long> signUp(@Valid @RequestBody UserSignUpRequest userSignUpRequest) {
          try {
              Long userId = userSignService.signUp(userSignUpRequest);
              return ApiResult.succeed(userId);
          } catch (Exception e) {
              log.error(e.getMessage());
              return ApiResult.failed(e.getMessage());
          }
      }
  
  		//...
  }

  • 설정파일에서 설정한 내용과 REST API 메서드에 설정된 애노테이션들이 어떻게 보여지는지 확인해볼 필요가 있습니다.
• 스프링 애플리케이션을 실행한 뒤, localhost:8080/swagger-ui.html 를 통해 초기 화면에 진입할 수 있습니다.

  • 앞서 설정한 API_NAME, API_VERSION, API_DESCRIPTION 등을 확인할 수 있습니다.

    

  • @ApiOperation과 @ApiResponses 의 내용을 확인할 수 있습니다.

    • Try it out 버튼을 활용해서 테스트도 가능합니다.
      • 필요한 요청(UserSignUpRequest)의 데이터를 기입한 후 Excute 버튼을 눌러 정보를 확인할 수 있습니다.