转载

Swagger 2(Open API v3.0) Java 文档生成指南(下)

先介绍网上“搜刮”的资源:

  • Swagger从入门到精通,如何编写基于 OpenAPI 规范的 API 文档, https://legacy.gitbook.com/book/huangwenchao/swagger/details https://blog.csdn.net/lucky373125/article/details/80471525
  • Swagger和OpenAPI https://www.breakyizhan.com/swagger/2806.html
  • Swagger 2与OpenAPI 3 https://www.jianshu.com/p/879baf1cff07

和Swagger UI的集成

怎么把这些 API 信息漂亮地展示出来呢? 接下来我们通过集成 Swagger UI 来实现。首先是下载 Swargger UI,它是一个 react 写成的纯前端项目,可以集成到任意服务端中,只要让可以读取到 API 的定义文件即可,所以呢,哪怕是 file:// 打开也行,它会解析可以访问到的 yaml/json 文件,渲染漂亮的文档出来。

Swagger UI 不过就是 HTML+JS+CSS,到 https://github.com/swagger-api/swagger-ui/tree/master/dist 下载,注意是 dist 发布版本。如果你前端动手能力强,可以使用非 dist 版的,通过 webpack 等其他方案集成。但那样就不是和 Java Web 项目集成了,另外一个 web service 服务在跑。我为了省事,集成在当前 java 项目中,用 tomcat 跑。

但也要注意一下访问权限的问题,不能让所有人都访问,特别是包含敏感信息的接口。

下载回来,解压,发现源码包含 map 用于调试的,好几兆呢,我们不要,只要 HTML/JS/CSS 便可。

Swagger 2(Open API v3.0) Java 文档生成指南(下)

运行一下,没毛病呢。

Swagger 2(Open API v3.0) Java 文档生成指南(下)

默认是 PetStore 的,打开 index.html 修改之。

Swagger 2(Open API v3.0) Java 文档生成指南(下)

修改为本地的即可。

最后,是不是觉得很简单呢?

还有很多好玩的,例如转换为 markdown,就要看看 swagger2markup https://blog.csdn.net/qq_34368762/article/details/79129303

原文  https://blog.csdn.net/zhangxin09/article/details/82707460
正文到此结束
Loading...