如何将Swagger OpenAPI规范添加到Spring Boot项目中？

Question

我发现了这个项目https://github.com/OAI/OpenAPI-Specification。据我所知，我们可以在.json/.yml文件中编写文档内容。同时我注意到，在http://editor.swagger.io/中可以将其呈现为.html文件。

我的问题是 - 如何从.json/.yml文件生成静态的.html页面？有没有关于spring boot应用程序的教程？我是否需要将.json/.yml文件设置为swagger配置以获得带有文档的.html文件？

- Orest

Answer 1

不需要从.yml或.json文件生成HTML、JavaScript和CSS资产的集合。只需将YAML/JSON文件传递给运行Swagger UI的服务器，Swagger UI将根据这些符合Swagger的API动态生成美观的文档。使用Swagger UI和petstore示例可以帮助理解。

您可以使用构建引擎（如Jenkins）自动化文档发布过程。例如，每个REST API存储库应至少提供其中一个.yml或.json文件（顺便说一下，这些文件是由Swagger Editor生成的）。然后，在对该存储库进行每次推送后，Jenkins将获取那些.yml或.json文件，并将它们上传到您的文档服务器上，其中Swagger UI正在运行。

REST API开发人员可以与客户端开发人员分享API文档链接，并且可以确信每个.yml或.json文件中的更改都将反映在文档中。他们只需要推送更改即可。由于您需要维护那些符合Swagger标准的API，我个人建议使用.yml文件，因为它更易读。

- Ali Dehghani

---

Swagger-UI能否从同一目录渲染JSON文件呢？例如，我在/static内容文件夹中有Swagger-UI，也有swagger.json文件。 - Orest

@Orest 应该是可以的。您只需要将 yml 文件链接传递给Swagger UI。 - Ali Dehghani

@AliDehghani - 我们如何通过Open API 3 UI传递自定义分页详细信息？ - PAA