头图

前后端交互的桥梁:RESTful API规范

swagger功能:

  • 【自动文档生成】定义 接口名称/路径/注释/分组标签/出入参字段/类型/是否必填, 可通过接口 swagger schema查看原始数据
  • 【在线测试】在线发送http请求进行测试

swagger schema生成途径

  • 【swagger自动生成】根据swagger api-docs接口获取json数据
  • 【模板手动添加】本地生成swagger scheme模板,再手动编辑这块原始数据,最后和后端对这份数据即可。在线验证及可视化查看:https://editor.swagger.io/

swagger schema 用途

这些功能可通过自定义cli实现,更加高效
  • 【接口代码生成】api.ts, api.d.ts文件 (根据swagger schema生成),使用ts可实现接口数据校验
  • 【接口数据mock】yapi 生成mock数据(根据swagger schema生成)
  • 【导入postman】可以使用更多postman高级的功能:变量,测试自动化,导出,参数记忆等功能;相比swagger web更高效、易用;

swagger cli功能开发

> swagger api init // 生成swaggerSchema.json本地模板,方便编辑
> swagger api api.d.ts [swagger url]  //根据swagger url地址生成api.d.ts和api.ts文件 
> jst api create -o src/services/api.d.ts swaggerTemplate.json -r @/utils/request   // 根据swagger url地址生成api.d.ts和api.ts文件 (支持自定义存储路径和api.ts中 require库的引入)

生成的swaggerSchema.json本地模板文件

{
    "swagger": "2.0",
    "info": {
        "description": "xxx接口管理",
        "version": "1.0",
        "title": "xxx服务端接口文档",
        "contact": {},
        "license": {
            "name": "MIT",
            "url": "http://opensource.org/licenses/MIT"
        }
    },
    "host": "petstore.swagger.io",
    "basePath": "/",
    "definitions": {
        "TmCallStartRequestDto": {
            "type": "object",
            "properties": {
                "callid": {
                    "type": "string",
                    "description": "描述信息"
                },
                "listenerUid": {
                    "type": "integer",
                    "format": "int64",
                    "description": "描述信息"
                }
            }
        },
        "TmResponseDto": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "string"
                },
                "data": {
                    "type": "array",
                    "description": "抄送列表",
                    "items": {
                        "type": "string"
                    }
                },
                "errMsg": {
                    "type": "string"
                },
                "msg": {
                    "type": "string"
                }
            }
        }
    },
    "tags": [
        {
            "name": "tel-call-hook-api",
            "description": "通话"
        }
    ],
    "paths": {
        "/call/tm/directcall/callbackstart": {
            "post": {
                "tags": [
                    "tel-call-hook-api"
                ],
                "summary": "tmAxbSuccess",
                "description": "接口描述",
                "operationId": "tmAxbSuccessUsingPOST",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "callStartRequestDto",
                        "description": "callStartRequestDto",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/TmCallStartRequestDto"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/TmResponseDto"
                        }
                    },
                    "201": {
                        "description": "Created"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                }
            }
        }
    }
}

生成的api.ts文件 (可在cli命令中,添加参数,在代码头部添加request路径)

// appUpload
 export async function AppUploadUsingPOST(params: Paths.AppUploadUsingPOST.Parameters.ConversionTypeDTO):Promise<Paths.AppUploadUsingPOST.Responses.$200> {
    return request('/baidu/app-upload', {
        method: 'POST',
        data: params,
    })
}

生成的api.d.ts文件,可通过npm库 dtsgenerator生成,也可以对它再封装一层,封装进你的命令中


tuihou123321
491 声望5 粉丝