[Spring] 스웨거 (Swagger) 설정하기

1. 스웨거 Swagger

https://swagger.io/

Swagger는 OAS(Open Api Specification)를 위한 오픈소스 프레임워크입니다.

즉, API의 문서를 자동으로 정리해주는 것 입니다.

---

2. 설정

2-1. @EnableSwagger2

Swagger2 버전을 활성화 하겠다는 어노테이션입니다.

2-2. Docket 빈 설정

Class Docket

Swagger 의 주 설정인 Docket Bean 등록 부분입니다.

 

1. 전체 범위 포함

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

 

2. 범위 설정(paths, api class or base package)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build()
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET,
                        Arrays.asList(
                                new ResponseMessageBuilder()
                                        .code(500)
                                        .message("server error")
                                        .responseModel(
                                                new ModelRef("Error")
                                        ).build()
                        )
                );
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger")
                .description("api list")
                .contact(new Contact("j", "https://ideahamster.tistory.com"))
                .version("1.0.0")
                .build();
    }
}

---

1) api()

select() method는 Swagger 설정 setting 이후 ApiSelectorBuilder 인스턴스를 리턴한다.

• apiInfo  : API 정보
  • useDefaultResponseMessages : 기본 반환 Message 설정
    • false로 설정하면, swagger에서 제공해주는 응답코드 ( 200,401,403,404 )에 대한 기본 메시지를 제거합니다.
    • 불필요한 응답코드와 메시지를 제거하기 위함이며, 컨트롤러에서 명시해줄 것입니다.
  • globalResponseMessage : 전반적인 반환 Message 셋팅
    • RequestHandlerSelectors.any() : 모든 url
    • RequestHandlerSelectors.none() : 사용 X
    • RequestHandlerSelectors.basePackage(String path) : path 에 해당하는 단위
•  apis() 
  • Swagger API 문서로 만들기 원하는 basePackage 경로입니다. (필수)
  • api 스펙이 작성되어 있는 패키지를 지정합니다. 즉, 컨트롤러가 존재하는 패키지를 basepackage로 지정하여,
    RequestMapping( GetMapping, PostMapping … )이 선언된 API를 문서화합니다.
• paths(Predicate selector)
  •  URL 경로를 지정하여 해당 URL에 해당하는 요청만 Swagger API 문서로 만듭니다.(필수)
  • apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화합니다.
  • PathSelectors 를 이용하여 path 에 대한 설정 가능 (**/api/*, /api/v1/* ..)
• groupName()
  • Docket Bean이 한 개일 경우 : 기본 값은 default이므로, 생략가능
  • 여러 Docket Bean을 생성했을 경우 : groupName이 충돌하지 않아야 하므로, 여기서는 각 Docket Bean의 버전을 명시해줬습니다.
• select() : ApiSelectorBuilder를 생성합니다.

---

2) getApiInfo()

Swagger API 문서에 대한 설명을 표기하는 메소드입니다. (선택)

제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출합니다.

파라미터 정보는 다음과 같습니다.
public ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )

• contact : 작성자 정보 

---

3. UI

api-docs url의 API data를 UI로 확인할 수 있는 내장 솔루션이다.

프로젝트 서버를 실행 후 다음 링크에서 확인해보자.

http://localhost:8080/your-app-root/swagger-ui.html
정상적으로 자신이 추가한 Controller 정보가 나온다면 설정에 성공한 것이다.

---

연관된 글 :

스웨거 Swagger

[Spring] Swagger 어노테이션

[Spring] 스웨거 (Swagger) v3 설정하기

 

참고:

Swagger 2 에서 Pageable 이용하기

4. swagger를 통한 문서화

[Spring boot] Swagger 설정하기

Spring REST API - Swagger2 연동

🙈[SpringBoot] Swagger - API Docs 자동화🐵

#5] Spring Swagger 설정하기

[SpringBoot] Swagger 설정하기

[Spring Boot / STS] 스프링부트에 swagger 연동 및 사용법[haddoddo]

[Spring Boot] Swagger 연동 및 설정 방법[Bamdule]

Spring Boot | Swagger 설정하기