[Spring Boot] Swagger 연동 및 설정 방법

1. Swagger란?

서버로 요청되는 URL 리스트를 HTML화면으로 문서화 및 테스트 할 수 있는 라이브러리입니다.

테스트는 Spring Boot 2.2.2 RELEASE에서 진행 되었습니다.

---

2. pom.xml

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

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

---

3. SwaggerConfig.java 

import java.util.HashSet;
import java.util.Set;
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.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;

/**
 *
 * @author MW
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.bamdule.controller"))
                .paths(PathSelectors.ant("/member/**"))
                .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 getApiInfo() {
        return new ApiInfoBuilder()
                .title("API")
                .description("[Bamdule] API")
                .contact(new Contact("Bamdule Swagger", "https://bamdule.tistory.com/", "Bamdule5@gmail.com"))
                .version("1.0")
                .build();
    }
}

• Swagger 설정을 정의한 코드입니다.
• .consume()과 .produces()는 각각 Request Content-Type, Response Content-Type에 대한 설정입니다.(선택)
• .apiInfo()는 Swagger API 문서에 대한 설명을 표기하는 메소드입니다. (선택)
• .apis()는 Swagger API 문서로 만들기 원하는 basePackage 경로입니다. (필수)
• .path()는 URL 경로를 지정하여 해당 URL에 해당하는 요청만 Swagger API 문서로 만듭니다.(필수)

---

4. Member.java

import io.swagger.annotations.ApiParam;

public class Member {

    @ApiParam(value = "member ID", required = true)
    private String id;

    @ApiParam(value = "member age", required = true)
    private int age;

    @ApiParam(value = "member email", required = true)
    private String email;
    
    //setter,getter 생략..
}

• @ApiParam 어노테이션은 멤버 변수에 대한 설명 및 다양한 설정을 지원합니다.
  • value : 저장되야 할 값에 대한 설명을 명시합니다.
  • required : 필수 여부를 지정합니다.

---

5. MemberController.java

import com.example.bamdule.TO.Member;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping(value = "/member")
public class MemberController {

    @ApiOperation(value = "Member Save", notes = "사용자 저장")
    @GetMapping(value = "/save")
    @ResponseBody
    public ResponseEntity saveMember(Member member) {
        
        /*
            member Save ...
        */

        return ResponseEntity.ok(member);
    }
}

• @ApiOperation : 메소드 설정 및 설명문을 기입합니다.
  
  • value : 메소드 설명
  • notes : 메소드 설명 2
• SwaggerConfig.java 에서 해당 Controller를 Swagger API 문서로 지정합니다.
• 브라우저를 통해 domain/contextPath/swagger-ui.html 로 이동하면 Swagger API 문서 페이지를 볼 수 있습니다.

---

6. Swagger API 문서 화면

Swagger API 문서 화면

• member-controller를 클릭합니다.

 

paramter 입력

• 화면에는 보이지 않지만 Try it out을 누른 후 Prameter를 입력해줍니다. 
• 입력이 완료되었다면, Execute 버튼을 눌러주세요.

 

• API 테스트에 대한 Code와 Detail한 응답 결과가 화면에 표시됩니다.