前后端交互的桥梁: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生成,也可以对它再封装一层,封装进你的命令中
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。