[spring boot 설정하기-4] Swagger 설정 및 사용 방법

개발하다보면 API를 정리해야 하는 경우가 생기는데 이를 자동으로 문서화 해주는 툴 중 하나입니다.

OAS(Open Api Specification)으로 API의 스펙(spec)을 관리할 수 있습니다.

아래 사이트에서 관련 정보를 볼 수 있습니다.

swagger.io/
https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

---

1. 의존성 추가

swagger2와 swagger-ui 2개를 기본적으로 추가해주어야 하는데 start를 추가하면 안에 다 들어있어서 편리합니다.

    // https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter
//    implementation group: 'com.spring4all', name: 'swagger-spring-boot-starter', version: '1.9.1.RELEASE'
    implementation "io.springfox:springfox-boot-starter:3.0.0"

2. swagger 사용 방법

패키지 형태는 아래와 같습니다.

 

2-1. 기본적인 사용에 대한 설정을 위해 SwaggerConfig.java 작성

package com.otrodevym.spring.base.common.swagger;

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

import java.util.ArrayList;


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private String version;
    private String title;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();

    }

    @Bean
    public Docket apiV1() {
        version = "V1";
        title = "base API " + version;

        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .groupName(version)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.base.swagger.api.v1"))
                .paths(PathSelectors.ant("/v1/api/**"))
                .build()
                .apiInfo(apiInfo(title, version));

    }

    @Bean
    public Docket apiV2() {
        version = "V2";
        title = "base API " + version;

        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .groupName(version)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.base.swagger.api.v2"))
                .paths(PathSelectors.ant("/v2/api/**"))
                .build()
                .apiInfo(apiInfo(title, version));

    }

    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfo(
                title,
                "Swagger로 생성한 API Docs",
                version,
                "www.base.com",
                new Contact("Contact Me", "www.base.com", "base@example.com"),
                "Licenses",
                "www.base.com",
                new ArrayList<>());
    }
}

• @EnableSwagger2 : Swagger2 버전을 활성화
• Docket : Swagger 설정의 핵심으로 문서화 객체, API에 대한 내용 및 스펙은 컨트롤러에서 작성
• 설정 정보
  • useDefaultResponseMessages() : swagger에서 제공해주는 응답코드 (200,401,403,404)에 대한 기본 메시지 사용 여부
  • groupName() :
    • Docket Bean이 한 개일 경우 기본 값은 default으로 생략가능
    • 여러 Docket Bean을 생성했을 경우 groupName이 출동할 수 있으므로 버전 명시
  • select() : ApiSelectorBuilder를 생성
  • apis()
    • api 스펙이 작성되어 있는 패키지를 지정
    • 컨트롤러가 존재하는 패키지를 basepackage로 지정하여, RequestMapping이 선언된 API를 문서화
  • paths() : path 조건에 해당하는 API를 찾아 문서화
  • apiInfo() : 제목, 설명 등 문서 정보를 위해 호출
    • public ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )

 

호출 방법은 swagger-ui를 쓰시면 됩니다.

http://localhost:9090/swagger-ui/

 

 

3. 스펙 작성을 위한 SwaggerContollerV1 작성

package com.otrodevym.spring.base.common.swagger;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;


@RestController
@Api(value = "SwaggerContollerV1")
@RequestMapping("/v1/api")
public class SwaggerContollerV1 {

    @ApiOperation(value = "sample", notes = "테스트")
    @ApiResponses({
            @ApiResponse(code = 200, message = "ok"),
            @ApiResponse(code = 500, message = "server error"),
            @ApiResponse(code = 404, message = "not found"),
    })
    @GetMapping(value = "/test")
    public Map<String, String> SwaggerTest(
            @ApiParam(value = "번호", required = true, example = "1") @RequestParam String no) {
        Map<String, String> result = new HashMap<>();

        result.put("name", "otrodevym");
        return result;
    }
}

• @Api : Swagger 리소스 명시
• value : 태그를 작성
• @ApiOperation : API에 대한 간략한 설명
• @ApiResponse : operation의 가능한 response를 명시
• @ApiParam : 파라미터 정보 명시