在 springdoc 中使用 openapi.yaml

Question

我可以通过代码自定义 OpenAPI 。
我可以像swagger-petstore
一样对 openapi.yaml 做同样的事情吗 ？我用一个 @RestController 创建简单的 springboot 项目。
我创建 openapi.yaml 并将其复制到 /src/main/resources/。
但我在打开的 swagger-ui 页面上看到默认值。

Answer 1

这可以从 spring-doc 文档中的常见问题解答页面获得。请参阅设置 Swagger UI 以使用提供的 spec.yml 的正确方法是什么？以及如何使用自定义 json/yml 文件而不是生成的文件？同一页面的。

常见问题解答页面的示例

1. 关闭项目属性文件中的自动生成springdoc.api-docs.enabled=false
2. 将您的 yaml 文件放入src/main/resources/static例如src/main/resources/static/myApiFile.yaml
3. 设置文件的 swagger-ui urlspringdoc.swagger-ui.url=/myApiFile.yaml
4. 启用最小bean配置

import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocsConfiguration {

  @Bean
  SpringDocConfiguration springDocConfiguration() {
    return new SpringDocConfiguration();
  }

  @Bean
  public SpringDocConfigProperties springDocConfigProperties() {
    return new SpringDocConfigProperties();
  }
}

Answer 2

openapi.yaml下面的代码是我们使用规范文件而不是从代码生成的默认文件所需执行的全部操作。

解释：

• org.springdoc.webflux.api.OpenApiResource是处理/v3/api-docs和/v3/api-docs.yaml端点的控制器。Swagger UI 使用该端点来显示 swagger ui 页面 - /swagger-ui.html。当您点击端点时，您可以看到配置/v3/api-docs/swagger-config。

• org.springdoc.webflux.api.OpenApiResource仅当 bean 丢失时才注册。你可以在 中看到它SpringDocWebFluxConfiguration。创建 bean 的方法用 进行注释@ConditionalOnMissingBean。所以你只需要扩展它并调整 OpenApi 规范检索（见下文）。

• org.springdoc.webflux.api.OpenApiResource正在使用getOpenApi()方法检索 OpenAPI 规范（默认情况下，规范是根据代码中的类注释生成的）。因此，您只需要重写getOpenApi()方法并提供 yaml 文件本身的规范（getYamlMapper()父类中也为您提供了方法，因此在下面的文件中确实很简单）

• 你可以看到OpenApiResource它在webflux包中，因为我们使用org.springdoc:springdoc-openapi-webflux-uiSpring WebFlux。Spring MVC 中的做法类似。

• 希望这会有所帮助:) 当您点击时，/swagger-ui.html您应该直接从 .yaml 规范中看到文档。当你点击时，/v3/api-docs你应该会看到 JSON 格式的规范本身。当您点击时，/v3/api-docs.yaml您应该会在 YAML 中看到规范本身。不需要 Spring 配置代码。只是控制器，如下所示:)

• 只是要明确一点。我们的 OpenAPI 规范位于src/main/resources/openapi/api.yaml

package com.your.package;
...imports omitted for readability...
import org.springdoc.webflux.api.OpenApiResource;

@RestController
public class OpenApiController extends OpenApiResource {

  @Value("classpath:openapi/api.yaml")
  private Resource openAPIResource;

  private OpenAPI openAPI;

  public OpenApiController(ObjectFactory<OpenAPIBuilder> openAPIBuilderObjectFactory, AbstractRequestBuilder requestBuilder, GenericResponseBuilder responseBuilder, OperationBuilder operationParser, RequestMappingInfoHandlerMapping requestMappingHandlerMapping, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, Optional<ActuatorProvider> actuatorProvider) {
    super(openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, requestMappingHandlerMapping, operationCustomizers, openApiCustomisers, springDocConfigProperties, actuatorProvider);
  }

  @SneakyThrows
  @PostConstruct
  public void initOpenAPI() {
    openAPI = getYamlMapper().readValue(openAPIResource.getInputStream(), OpenAPI.class);
  }

  @Override
  protected synchronized OpenAPI getOpenApi() {
    return openAPI;
  }
}