spring-boot - 如何从 Spring 中生成的 OpenAPI 文档中排除“服务器”部分？

Question

OpenAPI 3.0 Spec 有一组固定字段，称为 OpenAPI 对象https://swagger.io/specification/

如果我默认启用 OpenAPI 规范，它将有一个servers部分（https://swagger.io/specification/#server-object），其中包含url和之类的详细信息description。我不想servers在我的 api-docs 文件中包含该部分。有没有办法禁用该servers部分？

Answer 1

我没有使用 Springfox OpenAPI 的经验，但我确实注意到在查看源代码时 spring-boot 自动配置注册了一个 bean，该 bean 会根据请求将服务器部分动态添加到规范中。

注册规范转换器的自动配置：

@Configuration
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@Conditional(OnServletBasedWebApplication.class)
@EnablePluginRegistries(WebMvcOpenApiTransformationFilter.class)
public class OpenApiWebMvcConfiguration {
  @Bean
  public WebMvcOpenApiTransformationFilter webMvcOpenApiTransformer(
      @Value(OPEN_API_SPECIFICATION_PATH) String oasPath) {
    return new WebMvcBasePathAndHostnameTransformationFilter(oasPath);
  }
}

添加到服务器部分的默认转换器的实现：

@Order(Ordered.HIGHEST_PRECEDENCE)
public class WebMvcBasePathAndHostnameTransformationFilter implements WebMvcOpenApiTransformationFilter {
  private static final Logger LOGGER = getLogger(WebMvcBasePathAndHostnameTransformationFilter.class);
  private final String requestPrefix;

  public WebMvcBasePathAndHostnameTransformationFilter(@Value(OPEN_API_SPECIFICATION_PATH) String oasPath) {
    this.requestPrefix = StringUtils.trimTrailingCharacter(oasPath, '/');
  }

  @Override
  public OpenAPI transform(OpenApiTransformationContext<HttpServletRequest> context) {
    OpenAPI openApi = context.getSpecification();
    context.request().ifPresent(servletRequest -> {
      ForwardedHeaderExtractingRequest filter
          = new ForwardedHeaderExtractingRequest(servletRequest, new UrlPathHelper());
      openApi.servers(Collections.singletonList(inferredServer(requestPrefix, filter.adjustedRequestURL())));
    });
    return openApi;
  }

  @Override
  public boolean supports(DocumentationType delimiter) {
    return delimiter == DocumentationType.OAS_30;
  }
}

如果找不到合适的解决方法，我会尝试注册一个WebMvcOpenApiTransformationFilter覆盖当前类型的新 bean。

例子：

@Configuration
public class AppConfig {

  @Primary
  @Bean
  public WebMvcOpenApiTransformationFilter customMvcOpenApiTransformer() {
    return new MyCustomOpenApiTransformationFilter();
  }
}



@Order(Ordered.HIGHEST_PRECEDENCE)
public class MyCustomOpenApiTransformationFilter implements WebMvcOpenApiTransformationFilter {
  @Override
  public OpenAPI transform(OpenApiTransformationContext<HttpServletRequest> context) {
    return context.getSpecification();
  }

  @Override
  public boolean supports(DocumentationType delimiter) {
    return delimiter == DocumentationType.OAS_30;
  }
}