springfox & springdoc

Java

Swagger

2023년 1월 21일

1. Swagger란?

개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다.

1-1. 주요 Swagger의 도구

Swagger 편집기: OpenAPI 정의를 작성할 수 있는 브라우저 기반 편집기
Swagger UI: OpenAPI 정의를 대화형 문서로 렌더링
Swagger Codegen: OpenAPI 정의에서 서버 스텁(data를 받고 local의 지정된 프로시저를 호출하는 역할) 및 클라이언트 라이브러리를 생성
Swagger Core: OpenAPI 정의를 만들고 사용하고 작업하기 위한 java 관련 라이브러리
Swagger APIDom: 다양한 설명 언어 및 직렬화 형식에서 API를 설명하기 위한 단일 통합 구조를 제공

1-2. Swagger를 사용하는 이유

Swagger를 사용하면 본인이 설계한 API를 깔끔한 형태로 한 눈에 볼 수 있다.
postman을 이용하지 않고도 API에 데이터를 전송해 작동하는 형태를 확인할 수 있다.
- postman에 대해서

2. Springfox Swagger

Spring으로 구축된 API에 대한 자동화된 JSON API 문서

2-1. 시작히기

2-1-1. Maven

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

2-1-2. Gradle

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2-2. SwaggerConfig 생성

@Configuration
@EnableSwagger2
public class SwaggerConfig {

// 기본 swagger 선언
@Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())
      .build();
  }
}

Docket Bean 공식 문서

2-3. Spring MVC 프로젝트인 경우 추가 설정

public class SwaggerConfig implements WebMvcConfigurer {
    
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resoucres/webjars/");
  }

  ... Docket Bean ...
}

3. Springdoc

위에서 소개한 Springfox와 동일한 기능을 하는 Spring으로 구축된 API에 대한 자동화된 JSON API 문서

3-1. 시작하기

3-1-1. Maven

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.9</version>
   </dependency>

3-1-2. Gradle

implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'

3-2. SwaggerConfig 설정하기

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Configuration
public class SwaggerConfig {
  @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String version) {
        
    Info info = new Info()
                .title("Documentation Title") // 문서 제목
                .version(version) // 문서 버전
                .description("Documentation Description") // 문서 설명
                .contact(new Contact() // 연락처
                        .name("Your name")
                        .email("Your email"));

      // Security 스키마 설정
        SecurityScheme bearerAuth = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("Authorization")
                .in(SecurityScheme.In.HEADER)
                .name(HttpHeaders.AUTHORIZATION);

        // Security 요청 설정
        SecurityRequirement addSecurityItem = new SecurityRequirement();
        addSecurityItem.addList("Authorization");

        return new OpenAPI()
                        // Security 인증 컴포넌트 설정
                        .components(new Components().addSecuritySchemes("Authorization", bearerAuth))
                        // API 마다 Security 인증 컴포넌트 설정
                        .addSecurityItem(addSecurityItem)
                        .info(info);
    }
}

3-3. Application.yml

application.properties에서 yml로 변경하려면 이름바꾸기를 통해 application.yml로 명명해주면 된다.
yaml/yml 파일 작성 방법
springdoc application.yml 작성 방법

3-3-1. 작성 예시

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  version: '1.0.0'
  api-docs:
    groups:
      enabled: true
  swagger-ui:
    operations-sorter: alpha
    tags-sorter: alpha
    enabled: true
    path: '/api/api-docs.html'
    try-it-out-enabled: false
    disable-swagger-default-url: true

3-4. 실행 화면

springboot 버전: 2.7.8
spring dependency-management 버전: 1.0.15.RELEASE
java 버전: 11 (17로 설정 후 실행 시 실행되지 않아 11로 변경...)

springdoc