使用 OpenAPI Maven 插件生成 API 文档答案

【问题标题】：Generate API Docs with OpenAPI Maven plugin使用 OpenAPI Maven 插件生成 API 文档
【发布时间】：2019-06-19 00:53:15
【问题描述】：

我正在尝试为从 OpenAPI 3 yaml 生成的 Spring REST 应用程序生成 API 文档端点（例如 /v3/api-docs）。

我注意到Maven plugin 有一个generateApiDocumentation 标志，不过我不确定它的作用。

不幸的是，SpringFox 还不支持 OpenAPI 3 —— 而且当我只想将初始 yaml 公开为 json 时，拥有基于反射的生成器似乎毫无意义。

【问题讨论】：

标签： spring maven swagger openapi

【解决方案1】：

我不确定是否理解您的问题，但可以尝试查看这篇文章：https://www.baeldung.com/spring-rest-openapi-documentation

您也可以查看文档https://github.com/springdoc/springdoc-openapi

基本上你只需要添加这个 maven 依赖项

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

之后，当您启动服务时，您可以使用以下路径检查您的主机：/swagger-ui.html，格式如下：

http//localhost:8080/swagger-ui.html

我希望我会帮助你。

【讨论】：

【解决方案2】：

https://springdoc.org/faq.html

设置 Swagger UI 以使用提供的 spec.yml 的正确方法是什么？

使用此属性，所有 springdoc-openapi 自动配置 bean 都被禁用：

springdoc.api-docs.enabled=false

然后通过添加这个 Bean 来启用最小 bean 配置：

@Bean
SpringDocConfiguration springDocConfiguration(){
   return new SpringDocConfiguration();
}
@Bean
public SpringDocConfigProperties springDocConfigProperties() {
   return new SpringDocConfigProperties();
}

然后配置自定义 UI yaml 文件的路径。

springdoc.swagger-ui.url=/my-api-docs.yaml

在这种情况下，您应该将 'my-api-docs.yaml' 放入 'src/main/resources/static/' 文件夹！

【讨论】：