[빵빵] Swagger 적용하기

유보라·2022년 9월 19일

빵빵

목록 보기

2/2

안녕하세요! 오늘의 포스팅 주제는 Swagger입니다!

Spring boot를 이용하여 REST API를 개발하는 사람이라면, API 명세서를 작성해본 경험이 있을 것입니다. API 명세서는 해당 API에 대한 정보를 정리한 문서로, API를 사용하게 될 클라이언트와 다른 서버 개발자에게 공유하는 것이 그 목적입니다!

Swagger란?

Swagger는 Open Api Sepcification(OAS)를 위한 프레임워크로, API 문서 자동화와 테스트 기능을 제공해줍니다. Swagger를 이용하면 변경사항이 있을 때마다 API 명세서를 직접 작성하거나 API를 이해하기 위해 소스코드를 살펴 볼 필요가 없게 됩니다. 약속된 규칙에 따라 json, yml 형식으로 표현해주면 html 페이지로 문서화해주고, 이를 통해 API를 이해할 수 있게 됩니다.

Swagger 실습

Swagger 환경 설정

개발환경

Spring Boot 2.7.1
Swagger 3.0.0
Java 11

springfox 의존성 추가하기

build.gradle > dependencies 우클릭 > generate > 'springfox' 검색

아래 3개를 Add해줍니다! springfox-boot-starter 만 add 해도 된다고 알고 있는데, 우선 전 다 해줬습니다😀

그리고 swagger가 spring boot 2.6 이후 버전에서는 path가 달라 오류가 발생한다고 해서 application.yml에 다음 코드를 추가해주었습니다. 이렇게 지정해주면 오류가 발생하지 않는다고 하네요!

spring:
   mvc:
     pathmatch:
        matching-strategy:ant_path_matcher

SwaggerConfig 설정

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private static final String API_NAME = "Bbang0 API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Bbang0 API 명세서입니다.";

    @Bean
    public Docket api() {
        Parameter parameterBuilder = (Parameter) new ParameterBuilder()
                .name(HttpHeaders.AUTHORIZATION)
                .description("Access Tocken")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();

        List<Parameter> globalParameters = new ArrayList<>();
        globalParameters.add(parameterBuilder);

        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(globalParameters)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.bbang0.adapter.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }

}