Question

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

Answer 1

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

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

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

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

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

Answer 2

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

Answer 3

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

Answer 4

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

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

Answer 5

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

总而言之，您只需将springdoc-openapi的maven依赖项添加到您的应用程序中，并在启动Run时转到路径 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：在浏览器中访问它，您将看到招摇的文档。

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

5 个答案: