如何从现有的 Spring Boot App 生成 OpenApi 3.0 规范？答案

【问题标题】：How to generate OpenApi 3.0 spec from existing Spring Boot App?如何从现有的 Spring Boot App 生成 OpenApi 3.0 规范？
【发布时间】：2019-09-20 03:14:24
【问题描述】：

我有一个项目（Spring Boot App + Kotlin），我希望有一个 Open API 3.0 规范（最好是 YAML）。 Springfox 库很好，但它们生成 Swagger 2.0 JSON。从我的控制器中的注释生成 Open Api 3.0 规范的最佳方法是什么？从头开始写是唯一的方法吗？

【问题讨论】：

Springfox 功能请求支持 OpenAPI 3.0：github.com/springfox/springfox/issues/2022

标签： spring-boot kotlin swagger openapi

【解决方案1】：

你也可以参考 https://www.baeldung.com/spring-rest-openapi-documentation 它提供了使用 springdoc-openapi 使用 SpringBoot 1.x 或 2.x 应用程序实现 OpenAPI 3.0 的教程。

总而言之，您只需将 springdoc-openapi 的 maven 依赖项添加到您的应用程序中，当您启动运行时，转到路径 http://server:port/v3/api-docs.yaml/，您将下载一个 yaml 格式的 Open API 3.0 规范文件，该文件由您的应用程序代码生成。

您可以使用 springdoc-openapi 做一些其他的事情，通过在 SpringBoot 应用程序运行时访问以下内容：

http://server:port/v3/api-docs：以 Json 格式提供您的规范文件。
http://server:port/swagger-ui.html：在浏览器中访问它，您将看到 swagger 文档。

【讨论】：

【解决方案2】：

我们在kotlin项目中使用了springdoc-openapi库，它满足了我们使用spring boot项目自动生成API文档的需求。

它会自动将 swagger-ui 部署到 spring-boot 应用程序

Swagger UI 页面应该在以下位置可用： - http://server:port/context-path/swagger-ui.html OpenAPI 描述将在以下 url 提供 json 格式： - http://server:port/context-path/v3/api-docs

将该库添加到您的项目依赖项列表中（无需额外配置）

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

【讨论】：

我在 pom.xml 中添加了这个依赖。 jar 已下载。它被添加到 maven 依赖项中，但我无法在您提到的路径中看到 OpenApi 描述。对我来说，路径是：localhost:15730/context-path/v3/api-docs你能帮忙吗？
"context-path" 是你的 spring 应用的上下文，如果没有修改，通常是 "/" :)

【解决方案3】：

我决定实现我自己的生成器https://github.com/jrcodeza/spring-openapi也许你也可以看看。它基于反射，支持javax和spring注解。它还基于 Jackson 注释生成继承模型（带有鉴别器）。此外，如果您想更改生成过程（例如，当您有自己的注释并需要调整生成的模式部分时），您可以定义自己的拦截器。您可以在运行时模式下使用它，也可以将其用作 maven 插件。还有 OpenAPI3 to java 客户端生成器，它根据 openapi3 规范生成模型。同样，它还会生成 Javax 注释和 Jackson 注释以进行正确继承。

【讨论】：

【解决方案4】：

如果您使用 jax-rs，本教程会有所帮助。它使用 Apache CXF 实现。我找不到任何其他使用 Spring Boot 并生成 Open API 3.0 规范的 jaxrs 实现。

您将需要这些依赖项：

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
    <version>3.2.4</version>
</dependency>

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.13.6</version>
</dependency>

这里是一般配置，更多细节在链接中：

@Configuration
@EnableAutoConfiguration
@ComponentScan(basePackageClasses = PeopleRestService.class)
public class AppConfig {
    @Autowired private PeopleRestService peopleRestService;
    @Bean(destroyMethod = "destroy")
    public Server jaxRsServer(Bus bus) {
        final JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();
        factory.setApplication(new JaxRsApiApplication());
        factory.setServiceBean(peopleRestService);
        factory.setProvider(new JacksonJsonProvider());
        factory.setFeatures(Arrays.asList(new OpenApiFeature()));
        factory.setBus(bus);
        factory.setAddress("/");
        return factory.create();
    }
    @Bean
    public ServletRegistrationBean cxfServlet() {
        final ServletRegistrationBean servletRegistrationBean = new ServletRegistrationBean(new CXFServlet(), "/api/*");
        servletRegistrationBean.setLoadOnStartup(1);
        return servletRegistrationBean;
    }
}

https://dzone.com/articles/moving-with-the-times-towards-openapi-v300-adoptio

【讨论】：

【解决方案5】：

您可以查看spring-restdocs 和restdocs-api-spec。

spring-restdocs 采用测试驱动的 API 文档方法，与 spring-fox 使用的内省驱动方法相比具有许多优势。 restdocs-api-spec 是 spring-restdocs 的扩展，增加了 API 规范支持。目前支持 OpenAPI2 OpenAPI3 和 Postman。

【讨论】：