用于将“swagger”格式文件转换为“重组文本”的工具
swagger2rst的Python项目详细描述
摇动至.rst转换器
为什么？
这些工具是作为我们使用的文档工具包的一部分编写的 在我们每天的工作中。工具包的主要思想是 可以自动创建和更新文档
我们工具包的其他部分是：
安装
$ pip install swagger2rst
用法示例
命令-swg2rst
必需的参数：-path-到一个swagger文件的路径（“json”或 “yaml”）---format(-f)-输出文件格式。目前只有“RST”是 支持（必需）
选项：---output(-o)-输出文件名（默认：stdout）- --template(-t)-自定义模板文件路径（默认： 模板/基本。）---examples(-e)-自定义示例定义 文件路径（“json”或“yaml”）---inline(-i)-put模式 在路径中定义，否则在单独的Data Structures 章节
示例：
> swg2rst samples/swagger.json -f rst -o /home/user/rst_docs/swagger.rst > swg2rst samples/swagger.json -f rst -o /home/user/rst_docs/swagger.rst -e /home/user/examples.yaml > cat docs/swagger.json | swg2rst -f rst -t templates/custom.rst | grep /api
其他增强功能
将gfm描述转换成restructedtext安装pandoc 并使用自定义jinja过滤器md2rst
> sudo apt-get install pandoc > pip install pypandoc
{{doc.info['description']|md2rst}}
自定义示例
自定义示例在json或yaml中描述。见samples 目录。
元素
array_items_count
所有数组中的元素数。从1到5。默认值：2。
definitions
通过定义模式将字段绑定到示例。关键是定义 引用路径，值是对象（键是字段名，值是 示例）：
json
{"definitions":{"#/definitions/Media":{"likes.count":10,"likes.data.user_name":"liked_user","user.user_name":"my_login"},"#/definitions/MiniProfile":{"user_name":"some_login","full_name":"John Smith"}}}
yaml
definitions:'#/definitions/Media':likes.count:10likes.data.user_name:liked_useruser.user_name:my_login'#/definitions/MiniProfile':user_name:some_loginfull_name:John Smith
paths
按路径将操作字段绑定到示例。应该定义路径，方法， 节（参数或响应）和字段名
json
{"paths":{"/users/{user-id}/relationship":{"post":{"parameters":{"action":"approve"},"responses":{"200.data":{"profile_picture":"picture","full_name":"Kevin Jones","id":10,"user_name":"kevin"}}}}}}
yaml
paths:/users/{user-id}/relationship:post:parameters:action:approveresponses:200.data.profile_picture:picture200.data.full_name:Kevin Jones200.data.id:10200.data.user_name:kevin
types
定义基本类型的示例。
支持的类型：-字符串-日期-日期-时间-数字-整数- 布尔型
json
{"types":{"string":"value","date":"2000-12-01","date-time":"2000-12-01T12:00:00.000Z","number":1.2,"integer":5,"boolean":false}}
yaml
types:string:valuedate:'2000-12-01'date-time:'2000-12-01T12:00:00.000Z'number:1.2integer:5boolean:false
示例优先级
如果一个字段有多个示例，则应用以下优先级规则
- 操作示例。
- 定义中的示例。如果架构具有嵌套架构，则 优先考虑最具描述性的示例。例如。： Media具有嵌套架构MiniProfile。对于user_namein likes在Media中，将从 #/definitions/Media/likes.data.user_name而不是来自 #/definitions/MiniProfile/user_name。
- 原始类型的示例。
欢迎加入QQ群-->： 979659372
