使用swagger管理rest api

中国灯招商网 2019-10-06


API as produc


背景

项目有部分rest api提供给第三方使用,这部分API的说明由技术文档人员编写。由于技术文档人员对API的理解出现偏差,所以API的文档可操作性需要进行改进。


我们在想:能不能开发人员在编写代码后,能直接生成API文档?因为开发人员对API的理解是最准确的。但是,生成API文档不能给开发人员带来额外工作量。

swagger

在经过研究后,认为比较符合api as a product理念。我们引进swagger来协助管理rest api。其整个流程可以看成:

生成文档

t

  • 开发人员开发基于jax-rs 注解的rest api(保持不变,不增加任何工作量)。

  • CI部署时候,使用swagger生成swagger.json(api document schema)。

  • CI提交swagger.json
    整个流程,对开发人员没有增加任何的工作量,无侵入性。

查看API文档

  • 访问API wiki网站,链接指向swagger ui服务器

  • 链接中swagger.json参数指向gitlab

安装swagger-editor


docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor


案例

  • 添加swagger插件in gradle


plugins {    id "io.swagger.core.v3.swagger-gradle-plugin" version "2.0.6"}
  • 添加swagger文档配置

resolve {
    outputFileName = 'user-service-api'
    outputFormat = 'JSON'
    prettyPrint = 'TRUE'
    classpath = sourceSets.main.runtimeClasspath
    resourcePackages = ['com..results.api']
    outputPath = 'out/test'}
  • 生成api

./gradlew resolve
  • 生成结果:


  • API文档展示