gateway-service

pom.xml

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

application.yml

spring.cloud.gateway:
  routes:
    - id: openapi
      uri: http://localhost:${server.port}
      predicates:
        - Path=/v3/api-docs/**
      filters:
        - RewritePath=/v3/api-docs/(?<path>.*), /api/v1/$\{path}/api-docs
    - id: auth-service
      uri: lb://auth-service
      predicates:
        - Path=/api/*/auth/**
      filters:
        - name: JwtAuthenticationFilter

springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    path: /swagger/ui

redirect 경로가 중요하다.

gateway 서버가 실행되면서 eureka에 있는 친구들의 `api-docs`를 호출한다.

그래서 물려있는 다른 서비스 들의 api-docs도 확인해야 한다.

GatewayApplication.java

import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.SwaggerUiConfigParameters;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.gateway.route.RouteDefinition;
import org.springframework.cloud.gateway.route.RouteDefinitionLocator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Lazy;

import java.util.ArrayList;
import java.util.List;

@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {

   public static void main(String[] args) {
      SpringApplication.run(GatewayApplication.class, args);
   }

   @Bean
   @Lazy(false)
   public List<GroupedOpenApi> apis(SwaggerUiConfigParameters swaggerUiConfigParameters, RouteDefinitionLocator locator) {
      List<GroupedOpenApi> groups = new ArrayList<>();
      List<RouteDefinition> definitions = locator.getRouteDefinitions().collectList().block();
      for (RouteDefinition definition : definitions) {
         System.out.println("id: " + definition.getId()+ "  "+definition.getUri().toString());
      }
      definitions.stream().filter(routeDefinition -> routeDefinition.getId().matches(".*-service")).forEach(routeDefinition -> {
         String name = routeDefinition.getId().replaceAll("-service", "");
         swaggerUiConfigParameters.addGroup(name);
         GroupedOpenApi.builder().pathsToMatch("/" + name + "/**").group(name).build();
      });
      return groups;
   }

}

auth-service

springdoc이 이미 설정되어 있다고 가정한다.

application.properties

springdoc.api-docs.path=/api/v1/auth/api-docs
springdoc.server.url=${SWAGGER_URL:http://localhost:8080}

SecurityConfig.java

.antMatchers("/v3/api-docs/**", "/swagger-ui.html", "/swagger-ui/**", "/api/*/auth/api-docs").permitAll()

gateway가 호출하는 부분들은 풀어준다.

이제 아래를 호출하면 확인할 수 있다.

http://{gatewayIp}:{gatewayPort}/webjars/swagger-ui/index.html

호출 테스트를 할 때 쿠버네티스 같은 곳에 들어가 있으면 서비스의 주소가 내부아이피로 보여서 테스트가 안될 수 있는데

다음과 같이 주소를 지정해 줄 수 있다.

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {

    @Value("${springdoc.server.url}")
    String serverUrl;

    @Bean
    public OpenAPI customOpenAPI() {
        // https://springdoc.org/faq.html
        // 함수별로 지정할 수 있다.
        // 단 함수의 @Operation 에 아래와 같이 추가해줘야 한다.
        // @Operation(summary = "함수 설명입니다.", security = {@SecurityRequirement(name = "bearer-key")})
        return new OpenAPI()
                .addServersItem(new Server().url(serverUrl))
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
    }

//    @Bean
//    public OpenAPI customOpenAPI() {
//        // https://stackoverflow.com/questions/70855605/how-to-ask-swagger-ui-to-add-bearer-token-field-for-each-endpoint-globally
//        // 전역으로 할 수 있는 자물쇠를 사용한다
//        return new OpenAPI()
//                .components(new Components()
//                        .addSecuritySchemes("bearer-key",
//                                new SecurityScheme()
//                                        .type(SecurityScheme.Type.HTTP)
//                                        .scheme("bearer")
//                                        .bearerFormat("JWT")
//                        )
//                )
//                .info(new Info()
//                        .title("Auth Service API")
//                        .description("Documentation of API v.1.0")
//                        .version("1.0")
//                ).addSecurityItem(
//                        new SecurityRequirement()
//                                .addList("bearer-jwt", Arrays.asList("read", "write"))
//                                .addList("bearer-key", Collections.emptyList())
//                );
//    }
}

[SpringDoc] SpringDoc을 사용한 OpenAPI 문서화 feat.Spring Cloud