[Spring] - 스프링 (gradle) springdoc으로 Swagger3 추가하기

문서화 작업의 필요성 

API를 개발하면 명세를 관리해야 한다. 명세란 해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해서 어떤 값을 요청하며, 이에 따른 응답 값으로 무엇을 받을 수 있는지를 정리한 자료이다.

 

이번 글에서는 스프링 gradle 프로젝트에서 springfox가 아닌

springdoc으로 Swagger3를 추가하는 방법에 대해 작성하고자 한다.

기존 springfox로 추가할려고 시도해보니.. 버전 업된 swagger3를 적용하는데 있어, 기존과는 다른 방법을 써야함을 느꼈다..

---

 

1. build.gradle에 아래의 의존성을 추가해준다. 

dependencies {
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

 

 

2. config 패키지를 만들고 SwaggerConfig.java 클래스를 만들어 내용을 보완한다. 

swagger3를 쓰고 있기 때문에

document를 참고해서 swagger2와 기능상 알맞는 문법과 메서드로 수정해줘야 한다. 

package com.example.api.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "Spring Boot Open API Test with Swagger",
                    description = "sample tests of CRUD controller",
                    version = "1.0")
)
@Configuration
public class SwaggerConfiguration {
    private OpenAPI openAPI(){
        return new OpenAPI();
    }
}

 

2 - 1. 추가적으로 메서드에 대한 세부 명세 내용은 Mapping위쪽에 Operation으로 작성할 수 있다. 

    @Operation(summary = "RequestParam 이용, 지정 전달자인 경우")
    @GetMapping(value = "/request1")
    public String getRequestParam1(
            @RequestParam (name = "name") String name,
            @RequestParam (name = "email") String email,
            @RequestParam (name = "organization") String organization
    ){
        return name + " " + email + " " + organization;
    }

 

 

3. Application을 실행시키고 http://localhost:8080/swagger-ui/index.html 로 접속한다.

그러면 아래와 같이 위에 작성한 내용을 반영한 나만의 Swagger API문서가 작성된 화면을 볼 수 있다!!