Gradle 환경에서 Swagger 사용 방법(API 문서 자동화)

Swagger란?

• 백엔드 개발에 있어 Rest API를 설계, 빌드, 문서화하는데 도움이 되는 오픈 소스 소프트웨어 프레임워크이다.

Swagger를 사용하는 경우

• 다른 개발팀과 협업 진행 시
• 백엔드의 API를 호출하는 프론트엔드 프로그램 제작 시

Swagger 적용 순서

1. bundle.gradle에 의존성 추가

2.application.yml에 다음과 같은 코드 추가

 

3.코드 작성(config패키지 생성 + SwaggerConfig 클래스 생성)

package com.example.board.config;

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


@Configuration
public class SwaggerConfig {

    // http://localhost:8080/swagger-ui/index.html
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.board.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger Test")
                .description("SwaggerConfig")
                .version("3.0")
                .build();
    }

}

다음과 같이 작성한 후에, .apis 코드 괄호부분에 자신이 만든 컨트롤러(적용하고자 하는 api)의 패키지명을 넣어주면 된다.

 

4. Controller 클래스에 @ApiOperation 어노테이션을 달아주고, value값과 notes값을 지정해준다.

ex) @ApiOperation(value="전체 게시글 조회",notes="전체 게시글을 조회합니다.")

=>value = api 정의(제목) notes = api 내용 설명(내용)

 

5. Springboot 실행 후, 다음 로컬주소로 들어간다.

http://localhost:8080/swagger-ui/index.html

그러면 자신이 만든 swagger ui를 다음과 같이 확인할 수 있다.

 

<참고 자료 및 출처>

https://blog.naver.com/sosow0212/222713025656

[스프링부트] Gradle 환경에서 Swagger 3.0 적용해보기 (API 명세서)