[Swagger] Swagger3 이론 및 Swagger 설정

김우진·2022년 9월 12일

swagger

목록 보기

1/3

들어가기 전...

이 게시글은 Spring boot에서 Swagger3를 적용시키는 내용에 대해 다루고 있습니다.
Swagger2와 Swagger3은 큰 차이는 없지만 사소한 부분들에서 다르니 버전에 주의 하시길 바랍니다.

Swagger란?

Swagger는 개발자가 REST 웹 서버로 요청되는 URL 리스트를 문서화 및 테스트 할 수 있는 프레임워크입니다.
원활한 소통과 개발에 집중하기 위해 API 명세서는 필수적입니다.
이를 엑셀등과 같이 문서로 작성할 수도 있지만 관리하기 어렵고 변경에 용이하지도 않습니다.
이에 API 명세 작성 및 관리에 많은 Tool들이 존재하는데 Swagger 역시 이들 중 하나입니다.

📌 참고 Swagger2와 Swagger3 swagger-ui 접속 URL 차이
Swagger2와 Swagger3의 swagger-ui 접속 URL이 다르니 주의 하세요!
Swagger2 = http://{{서버 주소}}:{{port}}/swagger-ui/index.html
swagger3 = http://{{서버 주소}}:{{port}}/swagger-ui.html

왜 Swagger인가?

위에서 말한 API 명세 문서 자동화 Tool중 Spring에는 대표적으로 Swagger와 Spring REST Docs가 있습니다.
여기서는 Spring REST Docs와 비교해 Swagger의 장단점을 알아보겠습니다. Spring REST Docs 역시 좋은 API 명세 문서이므로 자신의 상황에 맞는 기술을 잘 선택해 사용하시면 됩니다.

💭 Spring REST Docs는 제가 아직 Test Code 작성이 익숙치 않아 사용해보지 못하여 사용 후 게시글을 올리도록 하겠습니다.

Swagger 설정

Dependency 추가

우선, swagger를 사용하기 위해선 dependency를 추가해야 합니다.

[gradle]
implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

[maven]
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

설정 클래스 생성

Swagger에 대한 설정을 해줄 SwaggerConfig 클래스를 생성합니다.
이 클래스는 Swagger 문서가 적용될 package 지정, 문서에 대한 설명 등 전반적인 Swagger에 관한 내용을 설정합니다.

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("package 명"))
                .paths(PathSelectors.any())
                .build()
        );
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("API 문서 제목")
                .description("API 상세소개 및 사용법")
                .contact({{연락 내용}})
                .version("1.0")
                .build();
    }
}

Docket

Docket은 Swagger 설정을 도와주는 Class입니다.

useDefaultRespponseMessages : Swagger는 SwaggerConfig만 설정해줘도 기본적인 swagger-ui 페이지를 만들고 API 문서를 만들어 줍니다. 이때 API에 Default로 설정된 Message나 Response 등이 있는데 이를 사용할 지 정합니다.
select : ApiSelectorBuilder 클래스의 인스턴스를 반환합니다. 해당 인스턴스를 통해 Swagger의 end-point를 제어할 수 있습니다.
apis : api spec이 작성되어 있는 패키지를 지정합니다. RequestHandlerSelectors.any()로 설정한다면 전체 Api에 대한 문서를 나타낼 수 있습니다.
paths : path의 조건에 해당하는 Api를 문서화합니다. PathSelectors.any()로 한다면 전체 Api 패턴에 대한 문서를 나타낼 수 있습니다. PathSelectors.ant()로 특정 Api url pattern을 가진 Api만 문서를 만들 수도 있습니다.
apiInfo : 아래의 Swagger Api 문서에 대한 설정 객체를 등록해줍니다.