在 springdoc 中使用 openapi.yaml

Question

我可以从 code 自定义 OpenAPI。
我可以像 swagger-petstore
那样在 openapi.yaml 上做同样的事情吗我用一个 @RestController 创建了一个简单的 springboot 项目。
我创建 openapi.yaml 并将其复制到 /src/main/resources/.
但是我在 open swagger-ui 页面上看到了默认值。

Answer 1

如果需要配置文件，可以看FAQ，文档：

https://springdoc.org/faq.html#can-i-use-spring-property-with-swagger-annotations

下面是代码示例的 link：

https://raw.githubusercontent.com/springdoc/springdoc-openapi/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app15/SpringDocApp15Test.java

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 规范（默认情况下，规范是根据代码中的 class 注释生成的）。所以你只需要覆盖 getOpenApi() 方法并提供来自 yaml 文件本身的规范（getYamlMapper() 方法也在父 classes 中为你提供，所以它真的很简单在下面的文件中）
可以看到OpenApiResource在webflux包里，因为我们使用了org.springdoc:springdoc-openapi-webflux-ui、SpringWebFlux。在 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;
  }
}

Answer 3

这可以从 spring-doc 文档的常见问题解答页面获得。请参阅同一页的 What is a proper way to set up Swagger UI to use provided spec.yml? and How can use custom json/yml file instead of generated one ?。

FAQ 页面中的示例

关闭项目属性文件中的自动生成springdoc.api-docs.enabled=false
把你的yaml文件放在src/main/resources/static比如src/main/resources/static/myApiFile.yaml
为文件springdoc.swagger-ui.url=/myApiFile.yaml
启用最小 beans 配置

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();
  }
}

在 springdoc 中使用 openapi.yaml

Using openapi.yaml in springdoc

swagger

springdoc