如何从现有 Spring 引导应用程序生成 OpenApi 3.0 规范？

Question

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

Answer 1

你可以看看spring-restdocs and restdocs-api-spec。

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

Answer 2

如果您使用的是 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>

这里是一般配置，更多细节在link:

@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

Answer 3

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

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

Swagger UI 页面应该可以在以下位置找到： - http://server:port/context-path/swagger-ui.html 对于 json 格式，OpenAPI 说明将在以下 url 处提供： - http://server:port/context-path/v3/api-docs

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

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

Answer 4

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

Answer 5

您也可以参考 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/ 并且您将下载一个 Open API 3.0 规范文件，它是根据您的应用程序代码生成的 yaml 文件。

您可以使用 springdoc-openapi 做一些其他的事情，当您的 SpringBoot 应用程序是运行:

时访问以下内容

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

如何从现有 Spring 引导应用程序生成 OpenApi 3.0 规范？

How to generate OpenApi 3.0 spec from existing Spring Boot App?

kotlin

swagger

spring-boot

openapi