先介绍网上“搜刮”的资源:
- 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
- 官文注解: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
和 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 便可。
运行一下,没毛病呢。
默认是 PetStore 的,打开 index.html 修改之。
修改为本地的即可。
是不是觉得很简单呢?还有很多好玩的,例如转换为 markdown,就要看看 swagger2markup https://blog.csdn.net/qq_34368762/article/details/79129303
配置文件 openapi.yaml
配置文件 openapi.yaml 默认放在 classpath 中,才可以被读取。官方另外提供几种途径来编写 Swagger 的配置文件,这里就是不赘述了。
下面是配置文件的一个例子。
resourcePackages:
- com.foo.controller
prettyPrint: true
cacheTTL: 0
openAPI:
info:
version: '1.0'
title: 无忧在线 API
description: 'HTTP + JSON 接口,接口需要 token'
termsOfService: http://swagger.io/terms/
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: /wyzx-pc
值得注意的有:
- resourcePackages 要扫描的包名,可以不断添加。
- openAPI.servers 访问接口的前缀,也就是 Web 项目名称。这里配置正确了才能让 try it out 测试发送 HTTP 请求。