[Spring Boot] 스웨거(Swagger) 알아보기

⚙️ 개발 환경
IDE: IntelliJ
JDK: 11
Spring: SpringBoot 2.7.1 + Gradle

🔎 스웨거(Swagger) 란?

• RESTful API 문서를 자동으로 생성하고 관리하기 위한 도구이다.
• 프로젝트에 대해서 프론트엔드 개발자와 문서를 통하여 스펙을 명확하게 전달하고 관리하는 데 사용한다.

💻 스웨거(Swagger) 적용

1. 스웨거를 사용하기 위해서는 build.gradle 의존성을 추가해 주어야 한다.

dependencies {
	implementation 'io.springfox:springfox-swagger-ui:3.0.0'
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

2. Config 만들어주기

package com.smallgolemduo.togethersee.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.smallgolemduo.togethersee"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("같이 볼래?")
                .description("무비 추천 Restful API")
                .version("1.0")
                .build();
    }

}

3. application.yml 코드 추가하기

# swagger setting
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

📎 결과 페이지

⛔️ 주의사항

• 적용 후 올바른 UI 페이지가 나오지 않는다면 스웨거 버전을 확인이 필요하다. 버전에 따라서 Swagger UI 접속 url 이 다를 수 있다.

💡서버 실행 후 Swagger UI 접속

• Swagger 2.x인 경우 http://localhost:8080/swagger-ui.html
• Swagger 3.x인 경우 http://localhost:8080/swagger-ui/index.html

📚 스웨거(Swagger) 설정 및 옵션

Controller

• @Api: 해당 컨트롤러에 내용을 설정
• @ApiImpicitParams: 컨트롤러에 매핑될 파라미터들에 설정
• @ApiImpicitParam: 매핑될 파라미터 하나의 내용을 설정
• @ApiResponse: 응답 코드에 대한 설명
• @ApiOperation: 매핑 메서드에 대한 설명

Entity

• @ApiModelProperty: 속성의 내용, 예문, 필수여부 등을 설정