【总】前端 Swagger url 自动转 JavaScript方法(避免重复工作...)

前言

随着项目增多，且多数为项目定制化接口。避免前端重复封装，从 Swagger 入手，将 url 自动转 js 方法直接用。特别节约时间和资源~

Swagger 简介

Swagger 一款 RESTFUL 接口的、基于 YAML、JSON 语言的文档在线自动生成、代码自动生成的工具。

主要工具：

Swagger 编辑器：基于浏览器的编辑器，可以在其中编写 OpenAPI 规范，并实时预览 API 文档。
Swagger UI ：将 OpenAPI 规范呈现为交互式 API 文档，并可以在浏览器中尝试 API 调用。
Swagger Codegen ：根据 OpenAPI 规范，生成服务器存根和客户端代码库。

实现

目录结构

.
├─ js
|   ├─MySwagger.js         # 主文件，1.url转js接口；2.接口查询界面解析接口；
|   └─ swagger             
|       ├─ axios.js	    # axios 对象及 包装后的 get,post,put,delete 等方法
|       └─ utils.js     # 工具文件，导入 axios.js，设置外部传入的 axios，url 解析为js方法名，定义 promise 等
└─ components
 	└─MySwaggerApi.vue # 组件，转换后的文件查看

主文件说明

MySwagger.js 中有两类方法

initSwaggerApi ：用于生成 Js 接口；
initSwaggerDoc ：用于界面显示接口信息；

文件 swagger/axios.js 和 swagger/utils.js 将在最后贴出

import Utils from "./swagger/utils"
import axios from "axios"

// 请求法类型
const REQUEST_METHODS = [ 'get', 'post', 'put', 'delete', 'patch'];


export default class MySwagger {
    /**
     * 初始化 Swagger Javascript Api 接口
     * @param {Object} axios，axios对象，注意已带 token
     * @param {Object} cfg，swagger 相关信息 {ignorePaths, jsonUrl, ignorePaths}
     * @param {Function} callback 回调函数
     * @returns 
     */
    static initSwaggerApi(myaxios, cfg, callback) {
        // swagger/axios.js 文件中的方法，设置外部传入的 axios 对象
        Utils.setHttp(myaxios);
        // 解析 swagger json 对象
        axios.get(cfg.jsonUrl).then(res => {
            // paths 列表
            const paths = res.data.paths;

            for(const path in paths) {
                const methods = paths[path];

                for(const method in methods) {
                    if(!REQUEST_METHODS.includes(method)) {
                        continue;
                    }
                    // swagger/axios.js 文件中的方法，url 转换为 js 方法名
                    const apiMethodName = Utils.restUrlToMethodName(method, path, cfg.ignorePaths);

                    // 注意是 this，直接放在 类上，为静态方法。api 方法对象集合
                    this[apiMethodName] = function(odt, odt2, odt3) {
                        // swagger/axios.js 文件中的方法，定义 promise
                        return Utils.definePromise(path, method, odt, odt2, odt3)
                    };
                }
            }
            callback(true)
            console.log('Swagger API 自动转js方法成功！');
        }).catch(err => {
            callback(false)
            console.error('Swagger API 自动转js方法失败', err);
        })
    }
    
    /**
     * 初始化 Swagger Javascript Api 文档信息
     * @param {Object}   cfg swagger 相关信息 {jsonUrl, ignorePaths}
     * @param {Function} callback 成功回调 (data) 信息
     * @param {Function} errorback 失败回调 (e) 错误信息
     * @returns 
     */
    static initSwaggerDoc(cfg, callback, errorback) {
        let objs = {}
        // 解析 swagger json 对象
        axios.get(cfg.jsonUrl).then(res => {
            const data = res.data;
            // 判断 swagger 版本
            const version = (data.swagger || data.openapi).split('.')[0];
            // paths 列表
            const paths = data.paths;
			// swagger v2
            if(version==='2') { 
                for(const path in paths) {
                    const methods = paths[path];

                    for(const method in methods) {
                        // get/post 对象下
                        if(!REQUEST_METHODS.includes(method)) {
                            continue;
                        }
                        // swagger/axios.js 文件中的方法，url 转换为 js 方法名
                        const apiMethodName = Utils.restUrlToMethodName(method, path, cfg.ignorePaths);
                        const params = methods[method];
                        
                        const tag = params.tags[0];
                        if(!objs[tag]) {
                            objs[tag] = {
                                tag,
                                description: tag,
                                paths: []
                            }
                        }
                        objs[tag].paths.push({
                            path,
                            apiMethodName,
                            method,
                            summary: params.summary,// 接口描述
                            parameters: params.parameters,// 请求参数
                            version
                        })    
                    }
                }
            }
            else {// swagger v3，配置管理
                // 先解析 tag
                data.tags.forEach(t => {
                    objs[t.name] = {
                        tag: t.name,
                        description: `${t.name} ${t.description}`,
                        paths: []
                    }
                });
                // console.log('objs: ', objs);
                for(const path in paths) {
                    const methods = paths[path];

                    for(const method in methods) {
                        // get/post 对象下
                        if(!REQUEST_METHODS.includes(method)) {
                            continue;
                        }
                        // swagger/axios.js 文件中的方法，url 转换为 js 方法名
                        const apiMethodName = Utils.restUrlToMethodName(method, path, cfg.ignorePaths);
                        const params = methods[method];
                        
                        const tag = params.tags[0];
                        // console.log('objs[tag]', objs[tag], tag);
                        
                        // 要判断，有的 tags 与 path 不一致
                        objs[tag]?.paths.push({
                            path,
                            apiMethodName,
                            method,
                            summary: params.summary,// 接口描述
                            parameters: params.parameters,// 请求参数
                            version
                        })                
                    }
                }
            }
            callback(objs)
        }).catch(e => {
            errorback(e)
        })
    }    
}

功能使用

Swagger 解析配置

const SWAGGER_CFG = {
    // 过滤不必要的路径
    ignorePaths: ['v1/', 'myweb/'],
    // swagger json 文件
    jsonUrl: 'http://127.0.0.1:8000/swagger/v1/swagger.json',
    // swagger 接口文件地址
    docUrl: 'http://127.0.0.1:8000/swagger/index.html'
}

生成 Js 接口

代码第 13 - 20 行，创建 axios 对象，外部传入更灵活，可设置 token 等信息；
代码第 13 - 20 行，初始化 js 接口到 MySwagger 类上；

<template>
    <div>
        <h1>swagger测试</h1>
    </div>
</template>

<script>
import axios from 'axios'
import MySwagger from '../js/index'
export default {
    mounted() {
        // 外部传入更灵活，可设置 token 等信息
        const myAxios = axios.create({
            // 基地址
            baseURL: `${window.location.protocol}//${IP}:${PORT}/`,
            // 请求头带 token
            headers:{ 
                'Authorization': '111ssss22s2s2s2s2s2s22s22' 
            }
        })

        // 初始化 js 接口到 MySwagger 类上
        MySwagger 对象上.initSwaggerApi(myAxios, SWAGGER_CFG, (data) => {
            console.log(`初始化成功：${data}`);
        }, (err) => {
            console.log(`初始化失败：${err}`);
       })

       window.MySwagger = MySwagger;
    }
}
</script>

为方便查看 MySwagger 挂在 window。但不推荐…控制台输出可看到接口都挂到类上

在这里插入图片描述

接口界面

封装成组件 Vue <MySwaggerApi>；
代码第 4 行，可打开原始 Swagger 接口地址；
代码第 78 - 98 行，可复制接口；
代码第 104 - 111 行，调接口 MySwagger.initSwaggerDoc 获取列表；

<template>
    <div class="my-swagger-api__main">
        <div class="header">
            <el-link icon="el-icon-view" @click="openLink">Swagger 接口地址</el-link>
            <el-input v-model="searchKey" placeholder="路径搜索" @input="searchPath">
                <el-button icon="el-icon-search" ></el-button>
            </el-input>
        </div>
        <div class="main">
            <div class="row" v-for="item of tableData" :key="item.tag">
                <div class="first-title">{{item.description}}</div>
                <el-table class="api-list-table" :data="item.paths" border style="width: 100%" :row-class-name="tableRowClassName" @cell-click="onCopyText" >
                    <el-table-column type="expand" @click="copyHandle( 'icon-' + item.font_class)">
                        <template #default="props">
                            <el-form label-position="left" inline class="demo-table-expand">
                                <el-form-item label="请求方法：">
                                    <el-tag size="medium" :type="tagTypes[props.row.method]">
                                        {{ props.row.method }}
                                    </el-tag>
                                </el-form-item>
                                <el-form-item label="JS方法名：" >
                                    <el-tag size="mini" type="info">{{ props.row.apiMethodName }}</el-tag>
                                    <span></span>
                                </el-form-item>
                                <el-form-item label="描述：">
                                    <span>{{ props.row.summary }}</span>
                                </el-form-item>
                            </el-form>
                        </template>
                    </el-table-column>

                    <el-table-column prop="path" label="路径"> </el-table-column>
                    <el-table-column prop="apiMethodName" label="JS方法名" class-name="api-method-name-cell"> </el-table-column>
                    <el-table-column prop="summary" label="描述"> </el-table-column>
                </el-table>
            </div>
        </div>
    </div>
</template>

<script>
import MySwagger from '../js/MySwagger'
export default {
    props: {
        config: {
            type: Object,
            default() {
                return {
                    // ignorePaths: ['v1/'],
                    // jsonUrl: 'http://127.0.0.1:7008/swagger/v1/swagger.json',// 解析的 json 路径
                    // docUrl: 'http://127.0.0.1:7008/swagger/index.html' // 官方接口列表
                }
            }
        }
    },
    data() {
        return {
            tableData: {},//API_LIST,
            tagTypes: {
                post: 'success',
                get: '',
                put:'info',
                delete: 'danger',
                patch: 'warning'
            },
            searchKey: '',
        }
    },
    methods: {
        tableRowClassName({ row, rowIndex }) {
            // return `${row.method}-row`;
        },
        // 打开
        openLink() {
            window.open(this.config.docUrl, '_blank')
        },
        // 拷贝
        onCopyText(row, column, cell, event) {
            console.log(row, column, cell, event);
            if(column.property!=='apiMethodName') {
                return
            }
            // 获取输入框的内容
            const copyText = row.apiMethodName; 
            
            let copy = (e) => {
                e.preventDefault()
                e.clipboardData.setData('text/plain', copyText)
                // 提示用户复制成功
                this.$message({
                    type: 'success',
                    message: `${column.label} 复制成功`
                })
                document.removeEventListener('copy', copy)
            }
            document.addEventListener('copy', copy)
            document.execCommand('copy')
        },
        // 查询
        searchPath(val) {
            console.log(this.searchKey, val);
        }
    },
    mounted() {
        // 初始化
        MySwagger.initSwaggerDoc(this.config, (data=>{
            this.tableData = data;
            console.log('this.tableData',this.tableData);
        }),(e)=>{
            console.error('获取错误',e);
        });
    },
};
</script>

<style lang="scss" scoped>
.my-swagger-api__main {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    overflow: hidden;
    .header {
        padding: 50px 50px 20px 50px;
        display: flex;
        justify-content: space-between;
        width: 100%;
        .el-input {
            width: 350px;    
        }    
    }
}
.main {
    position: absolute;
    top: 100px;
    left: 50px;
    right: 50px;
    bottom: 50px;
    overflow: auto;
    .row {
        margin-bottom: 20px;
    }
}
.first-title {
    font-size: 17px;
    font-weight: 600;
    height: 45px;
    line-height: 45px;
    padding-left: 5px;
    border-left: 4px solid #0d64d4;
    color: #333;
    background:#f0f8ff;
}
.demo-table-expand {
    margin-left: 50px;
    background:#fafdff;

    :deep(.el-form-item) {
        display: block;
        .el-form-item__label {
            width: 90px;
        }
    }
}
.api-list-table {
    :deep(.api-method-name-cell) {
        cursor: pointer;
    }
}

</style>
<style lang="scss">

.get-row {
    background: rgba(97, 175, 254, .5) !important;
}
.post-row {
    background: rgba(73, 204, 144, .5) !important;
}
</style>

界面组件的使用

<template>
    <my-swagger-api :config="config"/>
</template>

<script>
import MySwaggerApi from '../components/MySwaggerApi.vue';
export default {
    components: {
        MySwaggerApi
    },
    data() {
        return {
            config: SWAGGER_CFG
        }
    }
}
</script>

效果

在这里插入图片描述

使用

此处只列出特殊的。

Post

{urlParams}

Post 方式，同时存在 Parameters 和 RequestBody
第一个参数：对象类型，RequestBody。如果没参数，就传 null；
第二个参数，对象类型，Parameters。注意 key 与下图一致；

// 第一个参数 RequestBody
const requestBody = { 
    ip: '127.0.0.1',
    port: '6163'
};

// 第二个参数 Parameters
const parameters = {
    dataSourceName: 'pg123'
};
MySwagger.postConfSpatDatasourceEdit(requestBody, parameters);

在这里插入图片描述

url + Params

/v1/gms/conf/set-default-slice-cache-db

Post 方式，同时存在 Parameters 和 RequestBody
第一个参数：对象类型，RequestBody。如果没参数，就传 null；
第二个参数，对象类型，Parameters。注意 key 与下图一致；

// 第二个参数 Parameters
const parameters = {
    id: 'pg123'
};
MySwagger.postConfSetDefaultSliceCacheDb(null, parameters).then(res=>{
   console.log(res);             
}).catch(err => {
	console.log(err);
})

在这里插入图片描述

Get

{urlParams}

Get 方式，在 URL 上赋值参数
第一个参数，对象类型，Parameters。注意 key 与下图一致；

// 第一个参数是对象类型，且 key 与下图一致
const parameters = {
    dataSourceName: 'pg123'
}

// 请求
MySwagger.getConfSpatDatasourceInfo(parameters).then(res=>{
    console.log(res);
}).catch(err => {
    console.error(err);
})

在这里插入图片描述

url + Params

/v1/gms/conf/spat/gdb-list

Get 方式，在 URL 上赋值参数
第一个参数，对象类型，Parameters。注意 key 与下图一致；

// 第一个参数是对象类型，且 key 与下图一致
const parameters = {
    gdbp: 'pg123'
}

MySwagger.getConfSpatGdbList(parameters).then(res=>{
    console.log(res);
}).catch(err => {
    console.log(err);
})

在这里插入图片描述

最后

swagger/axios.js

// 导入封装好的axios实例
let service;

export default {
    
    // axios实例，外部传入，用于外部设置 token
    setHttp(axios) {
        service = axios;
    },

    /**
     * get 请求
     * @param {String} url     必填，请求地址 
     * @param {Object} params  选填，与请求一起发送的 url 参数
     * @param {Object} options 选填，其它配置参数
     */
    get(url, params, options = {}) {
        // 是否解析带参数的url
        url = parseParamsUrl(url, params);
        // 参数
        const config = {
            method: 'get',
            url: encodeURI(url)
        }
        // 是否有 params
        if (params) config.params = params
        // 其它参数
        for (let key in options) {
            config[key] = options[key]
        }
        // console.log('get',config);
        return service(config)
    },
    /**
     * post 请求
     * @param {String} url     必填，请求地址 
     * @param {Object} data    选填，请求主体数据
     * @param {Object} params  选填，与请求一起发送的 url 参数
     * @param {Object} options 选填，其它配置参数
     */
    post(url, data, params, options = {}) {
        // 是否解析带参数的url
        url = parseParamsUrl(url, params);
        // 参数
        const config = {
            method: 'post',
            url: encodeURI(url)
        }
        // 是否有 params
        if (params) config.params = params
        // 是否有 data
        if (data) config.data = data
        // 其它参数
        for (let key in options) {
            config[key] = options[key]
        }

        // console.log('post',config);
        return service(config)
    },
    put(url, params) {
        const config = {
            method: 'put',
            url: encodeURI(url)
        }
        if (params) config.params = params
        return service(config)
    },
    delete(url, params) {
        const config = {
            method: 'delete',
            url: encodeURI(url)
        }
        if (params) config.params = params
        return service(config)
    }
}


/**
 * 解析 url 带参数
 * @param {String} url     必填，请求地址 
 * @param {Object} params  选填，与请求一起发送的 url 参数
 */
function parseParamsUrl(url, params) {
    if(params && Object.keys(params) && Object.keys(params).length > 0) {
        Object.keys(params).forEach(key => {
            // 对应的参数
            const reg = `{${key}}`;
            if(url.indexOf(reg) > -1) {
                url = url.replace(reg, params[key])
                
            }
        })
    }
    // console.log('url2', url);
    return url;
}

swagger/utils.js

import http from "./axios.js"

export default {
    
    // axios实例，外部传入，用于外部设置 token
    setHttp(axios) {
        http.setHttp(axios)
    },

    /**
     * url 转方法名
     * @param {*} method：get, post, put, delete, patch
     * @param {*} url
     * @returns 
     */
    restUrlToMethodName(method, url, ignorePaths) { 
        // 把 -或者 . 也换成 /
        url = url.replace(/-|\./g, '/');
        // 去除不要的
        ignorePaths.forEach(p=>{
            url = url.replace(p, '');
        })
        // 移除路径中的斜杠和参数占位符  
        const paths = url.split('/');
        const methodName = paths.reduce((x,y)=>{
            // 去掉 {}，首字符大写
            const part = y.replace(/\{.*?\}/g, '');
            // 首字符大写
            const part2 = part.charAt(0).toUpperCase() + part.slice(1);
            return x + part2;
        }, '') 
        
        return method + methodName;  
    },
    /**
     * 定义 promise
     * @param {String} url
     * @param {String} method：get, post, put, delete, patch
     * @param {Object} odt，如果方法是 get，此参数为 params。如果是 post，为 RequestBody
     * @param {Object} odt2，如果方法是 get，此参数为 options。如果是 post，为 params
     * @param {Object} odt3，如果方法是 post，为 params
     * @returns 
     */
    definePromise(url, method, odt, odt2, odt3) {
        let promise;
        switch(method) {
            case 'get': {
                promise = new Promise(function(resolve, reject) {
                    http.get(url, odt, odt2).then(function(resp) {
                        const d = resp.data;
                        (d && d.succ) ? resolve(d.obj||d): reject(d);
                    }).catch(e=>{
                        reject(e)
                    })
                })
                break;
            }
            case 'post': {
                promise = new Promise(function(resolve, reject) {
                    http.post(url, odt, odt2, odt3).then(function(resp) {
                        const d = resp.data;
                        (d && d.succ) ? resolve(d): reject(d);
                    })
                })
                break;
            }
        }
        return promise;
    },



}