初衷
记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了,这份文档维护起来就很困难了。于是发现了swagger,自动生成文档的工具。
swagger介绍
首先,官网这样写的:
Swagger – The World's Most Popular Framework for APIs.
因为自强所以自信。swagger官方更新很给力,各种版本的更新都有。swagger会扫描配置的API文档格式自动生成一份json数据,而swagger官方也提供了ui来做通常的展示,当然也支持自定义ui的。不过对后端开发者来说,能用就可以了,官方就可以了。
最强的是,不仅展示API,而且可以调用访问,只要输入参数既可以try it out.
效果为先,最终展示doc界面,也可以设置为中文:
针对python flask的swagger客户端:
flask-swagger
A Swagger 2.0 spec extractor for Flask
Install:
pip install flask-swagger
Flask-swagger provides a method (swagger) that inspects the Flask app for endpoints that contain YAML docstrings with Swagger 2.0Operationobjects.
class UserAPI(MethodView):def post(self): """ Create a new user --- tags: - users definitions: - schema: id: Group properties: name: type: string description: the group's name parameters: - in: body name: body schema: id: User required: - email - name properties: email: type: string description: email for user name: type: string description: name for user address: description: address for user schema: id: Address properties: street: type: string state: type: string country: type: string postalcode: type: string groups: type: array description: list of groups items: $ref: "#/definitions/Group" responses: 201: description: User created """ return {}
可以参考:/gangverk/flask-swagger
针对Java spring mvc的可以看这里:/woshimrf/p/5863318.html
针对swagger yaml本身的一些介绍:/book/huangwenchao/swagger/details
如果觉得《使用swagger作为restful api的doc文档生成——从源码中去提取restful URL接口描述文档...》对你有帮助,请点赞、收藏,并留下你的观点哦!