Spring Boot 프로젝트 Swagger UI 적용

Swagger는 API 문서를 대신 만들어주는 툴 입니다.

프론트엔드에서 API 호출이 안된다고 할때가 있는데 문서가 화가 되어 있고 테스트 가능하면? 

 

공유하고 프론트엔드 개발자와 협업이 편해집니다.

 

Swagger  2가지 방법이 있습니다. Springfox, Springdoc 이중에 Springdoc 사용해서 만들도록하겠습니다.

 

Spring boot 버전에 따라 스웨거 UI를 사용하기 위해 추가해야 하는 Springdoc 라이브러리가 다릅니다.. Spring boot 2.X 이전에는 springdoc-openapi-ui를 추가, Spring boot 3.X 이후에는 springdoc-openapi-starter-webmvc-ui를 추가해야 정상적으로 스웨거 UI를 사용할 수 있습니다.

 

지금은 Spring boot 3.2.3 작업중이라 springdoc-openapi-starter-webmvc-ui를 추가하도록하겠습니다.

 

Gradle 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.4.0'

 

- 페키지 구조 추가 config에는 SwaggerConfig 설정 파일 추가

- Controller 추가

- application.proprtties 설정 추가

 

SwaggerConfig

@Configuration /*설정파일*/
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Springdoc 테스트")
                .description("Springdoc을 사용한 Swagger UI 테스트")
                .version("1.0");
    }
}

 

application.proprtties 

springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.display-request-duration=true
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=method

springdoc.api-docs.path=/api-docs

springdoc.show-actuator=true
springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8
springdoc.writer-with-default-pretty-printer=true

 

Controller 

@RestController
@RequestMapping(value = "api/v1")
//@Tag(name = "Template", description = "템플릿 API Document")
public class MainController {
//    @RestController는 @Controller에 @ResponseBody가 추가된 것입니다.
//    API를 만들거기때문에 RestController 선언해서 사용할 예정입니다.

    @GetMapping("/main")
    @Operation(summary = "test", description = "테스트 API 입니다.")
    public String main(){
        return "ex_openApi";
    }

}

 

 

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

 

접속하면 

 

정상 동작을 확인하수있습니다.

 

저는 application.proprtties 에 server.servlet.context-path=/openapi 추가해서 URL에 openapi가 추가되었습니다.

 

추가 안하신분들은 http://localhost:8080/swagger-ui/index.html 접속하시면 됩니다.

 

감사합니다

 

github : https://github.com/heechul88/project_sample/tree/dev_swagger