Python实现处理apiDoc转swagger的方法详解

需要转换的接口

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

apiDoc格式

apiDoc代码中的格式如下:

/**
 * @api {方法} 路径 标题
 * @apiGroup Group
 * @apiDescription 描述这个API的信息
 *
 * @apiParam {String} userName 用户名
 * @apiParamExample {json} request-example
 * {
 * "userName": "Eve"
 * }
 *
 * @apiError {String} message 错误信息
 * @apiErrorExample {json} error-example
 * {
 * "message": "用户名不存在"
 * }
 * 
 * 
 * @apiSuccess {String} userName 用户名
 * @apiSuccess {String} createTime 创建时间
 * @apiSuccess {String} updateTime 更新时间
 * @apiSuccessExample {json} success-example
 * {
 * "userName": "Eve",
 * "createTime": "1568901681"
 * "updateTime": "1568901681"
 * }
 */function getUserInfo(username) {
 // 假如这个函数是根据用户名返回用户信息的
}

使用npm安装apidoc插件:

npm install apidoc

再新建对应的apidoc.json,格式如下:

{
 "name": "文档名",
 "version": "版本号",
 "description": "解释",
 "title": "标题",
 "url" : "地址"
}

然后在apidoc.json路径下执行命令可以生成接口文档(src是接口代码文件夹,apidoc是生成文档的文件夹):

apidoc -i src/ -o apidoc/

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

swagger格式

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

{
 "swagger": "2.0",
 "info": {
 "description": "1.0版本接口文档",
 "version": "1.0.5",
 "title": "智能医疗辅助平台",
 "termsOfService": "http://swagger.io/terms/"
 },
 "host": "http://localhost:8080",
 "basePath": "/",
 "tags": [],
 "paths": {},
 "definitions": {}
}

其中path是存放接口的,tags是存放的分组名列表,definitions是实体列表(json参数)

思路

使用apidoc包生成apidoc的json格式数据,然后使用python读取出接口地址、名字、组名、输入参数格式和例子、输出参数格式和例子等,然后根据swagger格式填入对应的数据即可生成swagger的json格式

我的话是会直接使用处理出的swagger的json格式的数据导入yApi中

代码

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

import re
import json
import demjson
import decimal


# 保存时会出现byte格式问题,使用这个处理
class DecimalEncoder(json.JSONEncoder):
 def default(self, o):
 if isinstance(o, decimal.Decimal):
 return float(o)
 super(DecimalEncoder, self).default(o)


# 分析例子转json,在这里可以自己添加规则
def analyze_demjson(json_data):
 item = json_data.replace("\\n", "").replace("\\", "").replace(" ", "")
 result_item = {}
 try:
 result_item = demjson.decode(item, encoding='UTF-8')
 except:
 print(item)
 return result_item


# 获取解析apidoc数据
def get_api_doc_data(name):
 data_list = None
 group_list = {}
 with open(name, mode='r', encoding="UTF-8") as f:
 data_list = json.load(f)
 for data in data_list:
 if data['group'] in group_list:
 group_list[data['group']].append(data)
 else:
 group_list[data['group']] = [data]
 return group_list


# 转为swagger写入
def set_swagger_data(data):
 swagger_json = {
 "swagger": "2.0",
 "info": {
 "description": "1.0版本接口文档",
 "version": "1.0.5",
 "title": "智能医疗辅助平台",
 "termsOfService": "http://swagger.io/terms/"
 },
 "host": "http://localhost:8080",
 "basePath": "/",
 "tags": [],
 "paths": {},
 "definitions": {}
 }
 # 添加分组
 for group_key in data:
 swagger_json['tags'].append({
 "name": group_key,
 "description": group_key
 })
 # 添加接口信息
 # 循环分组
 for group_key in data:
 # 循环每组列表
 for interface in data[group_key]:
 parameters = {}
 if 'parameter' in interface and 'fields' in interface['parameter']:
 # 获取参数demo信息
 content = ""
 if 'examples' in interface['parameter']:
 content = analyze_demjson(interface['parameter']['examples'][0]['content'])
 # 添加参数信息
 parameter_dict = {}
 for parameter in interface['parameter']['fields']['Parameter']:
 parameter_type = "None"
 if "type" in parameter:
 parameter_type = parameter['type'].lower()
 if parameter_type == 'number':
 parameter_type = "integer"
 parameter_item = {
 "description": parameter['description'].replace('<p>', '').replace('</p>', ''),
 "required": parameter['optional'],
 "type": parameter_type,
 "default": ''
 }
 if parameter['field'] in content:
 parameter_item['default'] = content[parameter['field']]
 parameter_dict[parameter['field']] = parameter_item
 parameters = {
 "in": "body",
 "name": interface['name'],
 "description": interface['name'],
 "required": "true",
 "schema": {
 "originalRef": interface['name'],
 "$ref": "#/definitions/" + interface['name']
 }
 }
 swagger_json['definitions'][interface['name']] = {
 "type": "object",
 "properties": parameter_dict
 }
 # 添加返回信息
 responses = {
 "200": {
 "description": "successful operation",
 "schema": {
 "originalRef": interface['name'] + "_response",
 "$ref": "#/definitions/" + interface['name'] + "_response"
 }
 }
 }
 schema = {
 "type": "object",
 "properties": {
 "errcode": {
 "type": "integer",
 "default": 0,
 "description": "编码,成功返回1"
 },
 "data": {
 "type": "object",
 "default": {},
 "description": "监管对象明细,包含表头和数据内容两部分"
 },
 "errmsg": {
 "type": "string",
 "default": "ok",
 "description": '编码提示信息,成功时返回 "ok"'
 }
 }
 }
 # 返回例子
 if "success" in interface:
 response_example = ""
 if len(interface['success']['examples']) == 1:
 response_example = analyze_demjson(interface['success']['examples'][0]['content'])
 else:
 response_example = analyze_demjson(interface['success']['examples']['content'])
 if 'data' in response_example and response_example['data'] != {}:
 schema['properties']['data'] = response_example['data']
 swagger_json['definitions'][interface['name'] + "_response"] = schema
 # 加入
 swagger_json['paths'][interface['url']] = {
 interface['type']: {
 "tags": [group_key],
 "summary": interface['title'].replace(interface['url'] + '-', ''),
 "description": interface['title'],
 "consumes": [
 "application/json"
 ],
 "produces": [
 "application/json"
 ],
 "parameters": [parameters],
 "responses": responses
 }}
 # 写入json文件
 with open('swagger_data.json', 'w', encoding="UTF-8") as json_file:
 json.dump(swagger_json, json_file, cls=DecimalEncoder, indent=4, ensure_ascii=False)


if __name__ == '__main__':
 group_data = get_api_doc_data('api_data.json')
 set_swagger_data(group_data)
作者:七仔的博客原文地址:https://www.cnblogs.com/baby7/p/python_apidoc_to_swagger.html

%s 个评论

要回复文章请先登录注册