1.1 swagger简介
swagger
rap
挺好的,但是和swagger比起来有点轻量。
先看看swagger的生态使用图:
其中,红颜色的是swaggger
官网方推荐的。
下面再细看看swagger的生态的具体内容:
swagger-ui
这玩意儿从名字就能看出来,用来显示API文档的。和rap
不同的是,它不可以编辑。
点击某个详细API的可以试。
swagger-editor
就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。
左边编辑,右边立马就显示出编辑内容来。
编辑swagger说明文件使用的是yaml
语法具体的内容可以去官网查看。
各种语言版本的根据annotation或者注释生成swagger说明文档的工具
目前最流行的做法,就是在代码注释中写上swagger相关的注释,然后,利用小工具生成swagger.json或者swagger.yaml文件。
目前官方没有推出。github上各种语言各种框架各种有,可以自己搜吧搜吧,这里只说一个php相关的。
swagger-php
:https://github.com/zircote/swagger-php
swagger-validator
这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。
例如:
docker hub地址为:https://hub.docker.com/r/swaggerapi/swagger-validator/
可以pull下镜像来自己玩玩。
swagger-codegen
代码生成器,脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。
有一定用处,Java系用的挺多。工业上应该不咋用。
mock server
这个目前还没有找到很合适的mock工具,包括rap也好,其他API文档工具也好,都做的不够完善,大多就是根据说明文件,例如swagger.json等生成一些死的静态的mock数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。