python处理apiDoc转swagger

断情殇

python处理apiDoc转swagger

需要转换的接口

现在我需要转换的接口全是nodejs写的数据，而且均为post传输的json格式接口
apiDoc格式

apiDoc代码中的格式如下：

1. /**
2. * @api {方法} 路径 标题
3. * @apiGroup Group
4. * @apiDescription 描述这个API的信息
5. *
6. * @apiParam {String} userName 用户名
7. * @apiParamExample {json} request-example
8. * {
9. *  "userName": "Eve"
10. * }
11. *
12. * @apiError {String} message 错误信息
13. * @apiErrorExample  {json} error-example
14. * {
15. *   "message": "用户名不存在"
16. * }
17. *
18. *
19. * @apiSuccess {String} userName 用户名
20. * @apiSuccess {String} createTime 创建时间
21. * @apiSuccess {String} updateTime 更新时间
22. * @apiSuccessExample  {json} success-example
23. * {
24. *   "userName": "Eve",
25. *   "createTime": "1568901681"
26. *   "updateTime": "1568901681"
27. * }
28. */function getUserInfo(username) {
29.   // 假如这个函数是根据用户名返回用户信息的
30. }

复制代码

使用npm安装apidoc插件：

1. npm install apidoc

复制代码

再新建对应的apidoc.json，格式如下：

1. {
2.   "name": "文档名",
3.   "version": "版本号",
4.   "description": "解释",
5.   "title": "标题",
6.   "url" : "地址"
7. }

复制代码

然后在apidoc.json路径下执行命令可以生成接口文档（src是接口代码文件夹，apidoc是生成文档的文件夹）：

1. apidoc -i src/ -o apidoc/

复制代码

生成后可以在apidoc文件夹中打开index.html查看生成的接口文档，生成文档时会生成一个api_data.json，下面会用到
swagger格式

这里我们暂时只需要关注参数为json的接口格式

1. {
2.     "swagger": "2.0",
3.     "info": {
4.         "description": "1.0版本接口文档",
5.         "version": "1.0.5",
6.         "title": "智能医疗辅助平台",
7.         "termsOfService": "http://swagger.io/terms/"
8.     },
9.     "host": "http://localhost:8080",
10.     "basePath": "/",
11.     "tags": [],
12.     "paths": {},
13.     "definitions": {}
14. }

复制代码

其中path是存放接口的，tags是存放的分组名列表，definitions是实体列表（json参数）
思路

使用apidoc包生成apidoc的json格式数据，然后使用python读取出接口地址、名字、组名、输入参数格式和例子、输出参数格式和例子等，然后根据swagger格式填入对应的数据即可生成swagger的json格式
我的话是会直接使用处理出的swagger的json格式的数据导入yApi中
代码

代码虽然在下面，但是是我临时着急用写的，有的地方是写死的，需要改，这里放出来主要是讲个大致的思路

1. import re
2. import json
3. import demjson
4. import decimal
7. # 保存时会出现byte格式问题，使用这个处理
8. class DecimalEncoder(json.JSONEncoder):
9.     def default(self, o):
10.         if isinstance(o, decimal.Decimal):
11.             return float(o)
12.         super(DecimalEncoder, self).default(o)
15. # 分析例子转json，在这里可以自己添加规则
16. def analyze_demjson(json_data):
17.     item = json_data.replace("\\n", "").replace("\", "").replace(" ", "")
18.     result_item = {}
19.     try:
20.         result_item = demjson.decode(item, encoding='UTF-8')
21.     except:
22.         print(item)
23.     return result_item
26. # 获取解析apidoc数据
27. def get_api_doc_data(name):
28.     data_list = None
29.     group_list = {}
30.     with open(name, mode='r', encoding="UTF-8") as f:
31.         data_list = json.load(f)
32.     for data in data_list:
33.         if data['group'] in group_list:
34.             group_list[data['group']].append(data)
35.         else:
36.             group_list[data['group']] = [data]
37.     return group_list
40. # 转为swagger写入
41. def set_swagger_data(data):
42.     swagger_json = {
43.         "swagger": "2.0",
44.         "info": {
45.             "description": "1.0版本接口文档",
46.             "version": "1.0.5",
47.             "title": "智能医疗辅助平台",
48.             "termsOfService": "http://swagger.io/terms/"
49.         },
50.         "host": "http://localhost:8080",
51.         "basePath": "/",
52.         "tags": [],
53.         "paths": {},
54.         "definitions": {}
55.     }
56.     # 添加分组
57.     for group_key in data:
58.         swagger_json['tags'].append({
59.             "name": group_key,
60.             "description": group_key
61.         })
62.     # 添加接口信息
63.     # 循环分组
64.     for group_key in data:
65.         # 循环每组列表
66.         for interface in data[group_key]:
67.             parameters = {}
68.             if 'parameter' in interface and 'fields' in interface['parameter']:
69.                 # 获取参数demo信息
70.                 content = ""
71.                 if 'examples' in interface['parameter']:
72.                     content = analyze_demjson(interface['parameter']['examples'][0]['content'])
73.                 # 添加参数信息
74.                 parameter_dict = {}
75.                 for parameter in interface['parameter']['fields']['Parameter']:
76.                     parameter_type = "None"
77.                     if "type" in parameter:
78.                         parameter_type = parameter['type'].lower()
79.                         if parameter_type == 'number':
80.                             parameter_type = "integer"
81.                     parameter_item = {
82.                         "description": parameter['description'].replace('<p>', '').replace('</p>', ''),
83.                         "required": parameter['optional'],
84.                         "type": parameter_type,
85.                         "default": ''
86.                     }
87.                     if parameter['field'] in content:
88.                         parameter_item['default'] = content[parameter['field']]
89.                     parameter_dict[parameter['field']] = parameter_item
90.                 parameters = {
91.                     "in": "body",
92.                     "name": interface['name'],
93.                     "description": interface['name'],
94.                     "required": "true",
95.                     "schema": {
96.                         "originalRef": interface['name'],
97.                         "$ref": "#/definitions/" + interface['name']
98.                     }
99.                 }
100.                 swagger_json['definitions'][interface['name']] = {
101.                         "type": "object",
102.                         "properties": parameter_dict
103.                     }
104.             # 添加返回信息
105.             responses = {
106.                 "200": {
107.                     "description": "successful operation",
108.                     "schema": {
109.                         "originalRef": interface['name'] + "_response",
110.                         "$ref": "#/definitions/" + interface['name'] + "_response"
111.                     }
112.                 }
113.             }
114.             schema = {
115.                 "type": "object",
116.                 "properties": {
117.                     "errcode": {
118.                         "type": "integer",
119.                         "default": 0,
120.                         "description": "编码，成功返回1"
121.                     },
122.                     "data": {
123.                         "type": "object",
124.                         "default": {},
125.                         "description": "监管对象明细,包含表头和数据内容两部分"
126.                     },
127.                     "errmsg": {
128.                         "type": "string",
129.                         "default": "ok",
130.                         "description": '编码提示信息，成功时返回 "ok"'
131.                     }
132.                 }
133.             }
134.             # 返回例子
135.             if "success" in interface:
136.                 response_example = ""
137.                 if len(interface['success']['examples']) == 1:
138.                     response_example = analyze_demjson(interface['success']['examples'][0]['content'])
139.                 else:
140.                     response_example = analyze_demjson(interface['success']['examples']['content'])
141.                 if 'data' in response_example and response_example['data'] != {}:
142.                     schema['properties']['data'] = response_example['data']
143.             swagger_json['definitions'][interface['name'] + "_response"] = schema
144.             # 加入
145.             swagger_json['paths'][interface['url']] = {
146.                 interface['type']: {
147.                     "tags": [group_key],
148.                     "summary": interface['title'].replace(interface['url'] + '-', ''),
149.                     "description": interface['title'],
150.                     "consumes": [
151.                         "application/json"
152.                     ],
153.                     "produces": [
154.                         "application/json"
155.                     ],
156.                     "parameters": [parameters],
157.                     "responses": responses
158.                 }}
159.     # 写入json文件
160.     with open('swagger_data.json', 'w', encoding="UTF-8") as json_file:
161.         json.dump(swagger_json, json_file, cls=DecimalEncoder, indent=4, ensure_ascii=False)
164. if __name__ == '__main__':
165.     group_data = get_api_doc_data('api_data.json')
166.     set_swagger_data(group_data)

复制代码

来源:https://www.cnblogs.com/baby7/p/python_apidoc_to_swagger.html
免责声明：由于采集信息均来自互联网，如果侵犯了您的权益，请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容，谢谢合作！