[SpringCloud] Swagger(Springdoc) 통합 설정

Spring Boot에서는 여러 개의 모듈이나 서비스를 포함하는 분산 시스템에서 API 문서를 통합하고자 할 때, 주로 Swagger 문서를 Aggregator 또는 Gateway에서 통합하는 방식이 사용된다. 이를 위해서는 각 서비스의 Swagger 문서를 중앙 집중화된 위치에서 통합하거나, 서비스 간에 문서를 병합하는 방법을 사용할 수 있다. 두 방식 중 어느 것을 선택할지는 시스템의 구성과 요구사항에 따라 다를 수 있다. 중앙 집중화된 위치에서 통합하는 경우 Gateway에 부하가 집중될 수 있지만, 서비스 간 문서 병합은 각 서비스가 직접적으로 책임을 지게 된다.

 

중앙에서 통합하는 방식

---

Spring Gateway나 중앙에서 각각의 서비스의 api-docs의 path를 호출하는 방식이다. 

springdoc:
  api-docs:
    # API 문서 생성 활성화 여부
    enabled: true
    # 사용할 OpenAPI 버전
    version: openapi_3_1

  # Swagger UI 설정
  swagger-ui:
    # Swagger UI 활성화 여부
    enabled: true
    # Swagger UI 접근 경로
    path: /swagger-ui.html
    # Swagger UI 구성에 대한 URL
    config-url: /v3/api-docs/swagger-config

    # 각 서비스의 OpenAPI 문서 URL 목록
    urls:
      - name: user-service
        url: /user-service/v3/api-docs
      - name: notice-service
        url: /notice-service/v3/api-docs
      - name: map-service
        url: /map-service/openapi.json
      - name: caring-service
        url: /caring-service/v3/api-docs
      - name: utility-service
        url: /utility-service/v3/api-docs
      - name: chat-service
        url: /chat-service/openapi.json

 

 

Springdoc, Swagger, OpenAPI??

---

이들은 API 문서 생성과 관리를 위한 도구 및 스펙에 대한 용어들로 각각 다른 개념이지만 서로 밀접하게 관련되어 있다.

Swagger

Swagger는 스펙의 이름이다. Swagger는 OpenAPI Specification의 이전 이름이었으며, 현재는 OpenAPI Specification으로 불린다. 따라서 Swagger 스펙은 OpenAPI 스펙의 일부라고 할 수 있다.
Swagger UI와 Swagger Editor와 같은 도구들이 있다. Swagger UI는 API 문서를 시각적으로 표현하고 상호 작용할 수 있게 해주는 웹 인터페이스이고 Swagger Editor는 Swagger 스펙을 작성하고 편집하는 데 사용된다.

OpenAPI

OpenAPI는 스펙의 이름이다. OpenAPI Specification은 API 설계를 문서화하고 표현하기 위한 스펙이며, Swagger 스펙의 현재 이름이다.
언어에 중립적이고 표준화된 스펙이다. OpenAPI는 YAML 또는 JSON 형식으로 API를 정의하며, 이는 언어에 중립적이어서 다양한 플랫폼 및 언어에서 사용할 수 있다.

Springdoc

Springdoc는 Spring Boot 프로젝트에서 OpenAPI를 쉽게 사용할 수 있게 해주는 라이브러리다. Springdoc는 OpenAPI 스펙을 기반으로 Spring Boot 애플리케이션의 API 문서를 생성하고 노출하는 데 사용된다.
Springdoc는 Spring Boot의 애노테이션과 함께 사용하여 코드베이스에서 API 문서를 자동으로 생성할 수 있다.
 
간단히 말해, Swagger는 초기에 개발된 API 스펙의 이름이고, 이것이 나중에 OpenAPI Specification으로 발전하게 되었다. OpenAPI는 언어에 중립적인 표준 스펙으로서 다양한 환경에서 사용된다. Springdoc는 Spring Boot 프로젝트에서 OpenAPI를 쉽게 사용할 수 있도록 지원하는 도구이다. 따라서 Springdoc은 Swagger 스펙 또는 OpenAPI 스펙을 따르며, Spring Boot 프로젝트에서의 통합을 간편하게 만들어준다.
 

 

Spring Boot 3.1.x springdoc

---

라이브러리

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")

Configuration

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                   .title("My API")
                   .description("설명")
                   .version("1.0");

        SecurityScheme jwtSecurityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER)
                .name("Authorization");

        SecurityScheme xAuthorizationId = new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY)
                .in(SecurityScheme.In.HEADER)
                .name("X-Authorization-Id");

        SecurityRequirement securityRequirement = new SecurityRequirement()
                .addList("bearerAuth")
                .addList("X-Authorization");

        Server server = new Server().url("/");
        return new OpenAPI()
                .info(info)
                .components(
                        new Components()
                                .addSecuritySchemes("bearerAuth", jwtSecurityScheme)
                                .addSecuritySchemes("X-Authorization", xAuthorizationId)
                )
                .security(List.of(securityRequirement))
                .servers(List.of(server));
    }
}