使用swagger管理rest api

背景

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

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

swagger

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

生成文档

开发人员开发基于jax-rs 注解的rest api（保持不变，不增加任何工作量）。
CI部署时候，使用swagger生成swagger.json(api document schema)。
CI提交swagger.json
整个流程，对开发人员没有增加任何的工作量，无侵入性。

查看API文档

访问API wiki网站，链接指向swagger ui服务器
链接中swagger.json参数指向gitlab

swagger.png

Swagger本地验证

安装swagger-editor

docker pull swaggerapi/swagger-editor

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

案例

User service

添加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

生成结果:

file_path.png

API文档展示

api_doc1.png

api_doc2.png

api_doc3.png

详见