4

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

4

3 回答 3

4

这可以从 spring-doc 文档中的 FAQ 页面获得。请参阅设置 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();
  }
}
于 2021-11-21T22:56:42.790 回答
1

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.OpenApiResourcebean 仅在丢失时才注册。你可以在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;
  }
}
于 2020-10-29T10:49:56.140 回答