当前位置:主页 > python教程 > Python apiDoc转swagger

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

发布:2023-04-22 09:10:01 59


给网友朋友们带来一篇相关的编程文章,网友文英悟根据主题投稿了本篇教程内容,涉及到Python、apiDoc转swagger、Python、apiDoc、swagger、Python apiDoc转swagger相关内容,已被412网友关注,涉猎到的知识点内容可以在下方电子书获得。

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('

', '').replace('

', ''), "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)

到此这篇关于Python实现处理apiDoc转swagger的方法详解的文章就介绍到这了,更多相关Python apiDoc转swagger内容请搜索码农之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持码农之家!


参考资料

相关文章

  • sublime text 3配置使用python操作方法

    发布:2022-10-17

    为网友们分享了关于python的教程,下面小编就为大家带来一篇sublime text 3配置使用python操作方法。小编觉得挺不错的,现在就分享给大家,也给大家做个参考。一起跟随小编过来看看吧


  • Python经典案例之图像漫水填充分割详解

    发布:2023-03-13

    图像分割是将图像分成若干具有独特性质的区域并提取感兴趣目标的技术和过程,这篇文章将详细讲解漫水填充分割应用,感兴趣的小伙伴可以了解一下


  • 机器学习的框架推荐Python的原因

    发布:2019-09-15

    这篇文章主要为大家详细介绍了机器学习的框架偏向于Python的13个原因,具有一定的参考价值,感兴趣的小伙伴们可以参考一下


  • python仿抖音表白效果制作

    发布:2020-04-06

    这篇文章主要教大家制作python抖音表白神器,仿制抖音表白小软件,具有一定的参考价值,感兴趣的小伙伴们可以参考一下


  • python中os和sys模块的区别与常用方法总结

    发布:2022-10-27

    为网友们分享了关于python的教程,这篇文章主要给大家介绍了关于python中os和sys模块的区别与常用方法的相关资料,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面来一起


  • Python基础学习之函数和代码复用详解

    Python基础学习之函数和代码复用详解

    发布:2022-09-14

    给网友朋友们带来一篇关于Python 函数的教程,函数能提高应用的模块性,和代码的重复利用率,下面这篇文章主要给大家介绍了关于Python基础学习之函数和代码复用的相关资料,文中通过实例代码介绍的非常详细,需要的朋友可以参考下


  • python中向二维数组中添加整行或者增列元素问题

    发布:2023-04-24

    这篇文章主要介绍了python中向二维数组中添加整行或者增列元素问题,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教


  • Python3 SSH远程连接服务器的步骤方法

    发布:2019-06-15

    这篇文章主要介绍了Python3 SSH远程连接服务器的方法示例,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧


网友讨论