Spring - Swagger

Swagger란?

RestAPI로 개발시 문서를 자동으로 만들어주는 프레임워크

• 서비스의 API들에 대한 테스트를 해볼 수 있는 도구
• 해당 API의 스펙을 자동으로 문서화할 수 있다.
• API의 입력값 예시, 응답값, 오류 코드 등 확인하기 편리하다.

의존성 추가

swagger를 사용하기 위해서는 SPringfox-swagger2를 의존성에 추가해야함.

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

 

Swagger 실행

Swagger설정 값을 스프링 Bean에 등록

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.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


import java.util.ArrayList;
import java.util.List;

// Swagger 설정
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        List<ResponseMessage> responseMessages = new ArrayList<>();
        responseMessages.add(new ResponseMessageBuilder().code(200).message("OK").build());
        responseMessages.add(new ResponseMessageBuilder().code(404).message("FAIL").build());
        responseMessages.add(new ResponseMessageBuilder().code(500).message("SERVER INTERVAL ERROR").build());
        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("V1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wmp.epdev.api")) // API 문서를 만들어줄 범위(package)를 지정.
                // API의 URL 경로를 지정한다. PathSelectors.ant("user/**") 로 지정하는 경우, user ~ 하위 경로에 해당하는 문서를 생성
                .paths(PathSelectors.any())
// swagger에서 보여주는 status 응답코드에 대한 설정 메시지를 사용한다.
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, responseMessages)
                .build()
                .apiInfo(info());
    }

    private ApiInfo info() {
        return new ApiInfoBuilder()
                .title("Example 코드")
                .description("이것 저것 테스트해보는 프로젝트입니다.")
                .build();
    }
}

설정 관련 내용 설명

• @EnableSwagger2: Swagger2 버전을 활성화
• Docker: Swagger 설정의 핵심이 되는 Bean. (단, API 자체에 대한 스펙은 컨트롤러에 작성이 됨)
• groupName(): Docket Bean이 한개일 경우에는 생략가능. 여러 Docket Bean을 생성했을 경우에는 groupName이 충돌하지 않아야 하기 때문에, 네이밍을 해준다
• select(): ApiSelectorBuilder를 생성 (apis()와 paths()를 사용할 수 있게 해줌)
• apis(): API 스펙이 작성되어 있는 패키지를 지정한다 (RequestMapping 어노테이션 선언이 되어있는 것들이 작성 대상이다)
• paths(): apis()로 선택되어진 API중, 특정 path 조건에 맞는 API들을 필터링한다
• useDefaultResponseMessages(boolean b): false로 설정되면, swagger에서 제공해주는 응답코드(200, 401, 403, 404)에 대한 기본 메시지를 제거 - 기본 응답데이터 메시지 사용여부
  불필요한 응답코드와 메시지를 제거하기 위한 목적을 가지며, 컨트롤러에서 명시해준다
• globalResponseMessages(RequestMethod, List<ResponseMessage>): 설정한 응답 메시지 적용(RequestMethod는 METHOD별로 분리해서 적용가능하거나, valueOf()를 통해 전체 METHOD적용도 가능할듯..?)
• apiInfo(ApiInfo): 제목, 설명 등 문서에 대한 정보들을 보여주기 위해 사용

ApiInfo Class 확인

public ApiInfo(
    String title, // 1]
    String description, // 3]
    String version, // 2]
    String termsOfServiceUrl, // 4]
    Contact contact, // 5]
    String license, // 7] text
    String licenseUrl, // 7] url
    Collection<VendorExtension> vendorExtensions)

컨트롤러에 사용하는 어노테이션 적용

@Api: 해당 클래스가 Swagger 리소스라는 것을 명시

    - value: 태그를 작성

    - tags: 여러개의 태그를 정의

@ApiOperation: 한개의 API URI와 Method를 선언

    - value: API에 대한 간략한 설명

    - notes: 상세 내용 작성

@ApiResponse: Response를 명시

    - code: 응답코드

    - message: 응답에 대한 설명

    - responseHeaders: 헤더를 추가

@ApiParam: 파라미터에 대한 정보를 명시

    - value: 파라미터 정보를 작성

    - required: 필수 파라미터인 경우 true

    - example: 테스트를 할 경우에 보여줄 예시

@ApiImplicitParam: 파라미터 정보를 기술한다

@ApiImplicitParams: 파라미터가 여러개일 경우 감싸주는 어노테이션

@ApiModelProperty: Model프로퍼티 설명을 기술할 경우 사용

 

어노테이션 더 확인하기 (참고)

GitHub - swagger-api/swagger-core: Examples and server integrations for generating the Swagger API Specification, which enables

서버실행후, 화면에서 실행하는 방법

=> http://{domain}/swagger-ui.html (로컬환경인경우 localhost:8080)

 

(!) 왜 swagger-ui.html일까?

springfox-swagger-ui 라이브러리가 위의 그림과같이 만들어주기 때문

Swagger 실행화면