背景
項(xiàng)目有部分rest api提供給第三方使用凤价，這部分API的說(shuō)明由技術(shù)文檔人員編寫(xiě)鸽斟。由于技術(shù)文檔人員對(duì)API的理解出現(xiàn)偏差，所以API的文檔可操作性需要進(jìn)行改進(jìn)利诺。
我們?cè)谙耄耗懿荒荛_(kāi)發(fā)人員在編寫(xiě)代碼后富蓄，能直接生成API文檔？因?yàn)殚_(kāi)發(fā)人員對(duì)API的理解是最準(zhǔn)確的慢逾。但是立倍，生成API文檔不能給開(kāi)發(fā)人員帶來(lái)額外工作量灭红。
swagger
在經(jīng)過(guò)研究后，認(rèn)為比較符合api as a product理念口注。我們引進(jìn)swagger來(lái)協(xié)助管理rest api变擒。其整個(gè)流程可以看成：
生成文檔
- 開(kāi)發(fā)人員開(kāi)發(fā)基于jax-rs 注解的rest api（保持不變，不增加任何工作量）寝志。
- CI部署時(shí)候娇斑，使用swagger生成swagger.json(api document schema)。
- CI提交swagger.json
整個(gè)流程材部，對(duì)開(kāi)發(fā)人員沒(méi)有增加任何的工作量毫缆，無(wú)侵入性。
查看API文檔
- 訪(fǎng)問(wèn)API wiki網(wǎng)站乐导，鏈接指向swagger ui服務(wù)器
- 鏈接中swagger.json參數(shù)指向gitlab
swagger.png
Swagger本地驗(yàn)證
安裝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
- 生成結(jié)果:
file_path.png
-
API文檔展示
api_doc1.png
api_doc2.png
api_doc3.png
