Swagger 사용방법(feat.springdoc)

Swagger

색깔이 맘에 든다.

swagger는 api 문서 작업을 대신해주는 OpenAPI Specification 프레임워크이다.

백엔드와 프론트엔드가 소통하기 위해서는 restfulAPI로 작성한 코드를 정리한 문서가 필요하다.

/user/signup : user 회원가입

/user/login : user 로그인

/user/mypage : user 마이페이지

등등 api 스펙들을 적어놓는다.

이런식으로 수동으로 문서 작업하는것은 시간도 잡아먹고 실수할 우려도 있다. (사실 귀찮다)

swagger는 이러한 문서 작업을 자동으로 대신 해주고 해당 문서를 /swagger-ui/ 로 접근하면 문서 페이지를 그려준다.

또한 포스트맨에서 했던 요청 테스트도 swagger ui 페이지를 통해 가능하다.

너가해

어떻게 대신 해주는거지

스웨거는 자바 뿐만아니라 파이썬,자바스크립트 등 많은 언어에서 사용가능하다. 즉 스프링 전용 프레임워크가 아니다.

스프링에서 스웨거를 사용하기 위해서는 swagger ui, swagger 어노테이션으로 api 메타 정보 읽기 등을 전부 구현해주어야하는데..

이런 작업은 SpringDoc 또는 SpringFox 라이브러리가 해준다!

참고)

SpringFox : 2020년 이후 업데이트 중지 (spring boot 2.6 이상에서는 적용 안됨)

SpringDoc: 업데이트 진행중

검색했을 때 spring fox가 많이 나와서 그거썼는데 알아보니 spring doc가 계속 업뎃도 하고 더 많은 환경(webflux)을 지원한다고 하니

spring doc로 해봐야겠다.

개발환경

⚙️	version
java	11
springboot	2.6.5
build	gradle 8.5
swagger	3
springdoc-openapi-ui	1.6.9

설정

build.grade

dependencies{
    ...
    // swagger
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'
    ...
}

 

application.properties

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

SpringBoot 2.6 이상 버전으로 일때

요청 경로를 ControllerHandler에 매칭시키기 위해서 작성이 필요하다.

(spring.mvc.pathmatch.matching-strategy 기본값이 path_pattern_parser로 변경되었기 때문에 지정해주어야함.)

 

더 많은 설정을 원한다면 공식문서에서 확인하면 된다.

https://springdoc.org/properties.html

 

springfox 는 config클래스에서 설정을 해주는데

springdoc은 application.properties에서 해준다.

 

SwaggerConfig.java

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

/**
 * Swagger springdoc-ui 구성 파일
 */

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("User API Document")
                .version("v0.0.1")
                .description("이커머스 user api 명세서입니다.");
        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

 

/swagger-ui.html/ 접속