七仔的博客

七仔的博客GithubPages分博

0%

python处理apiDoc转swagger

发表于 更新于 分类于

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

python处理apiDoc转swagger

需要转换的接口

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

apiDoc格式

apiDoc代码中的格式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/**
 * @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插件：

1
npm install apidoc

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

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

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

1
apidoc -i src/ -o apidoc/

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

swagger格式

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "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中

代码

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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.baby7blog.com/myBlog/82.html

欢迎关注我的其它发布渠道