swagger-api-generator
v1.0.35
Published
generate api function by swagger
Downloads
12
Maintainers
Readme
swagger-api-generator
Generate dependent files of api request for your front-end project
Install
npm install swagger-api-generator -g
Alias
SAG: swagger-api-generator
SwaggerJson: 指用户(你)提供的Json输入源,本地的.swagger.json或者http://~.swagger_doc
Usage
Via swagger-api-config.json
——swagger-api-config.json
{
"inputMode": "json", // "json", "url"
"inputPath": "./swagger.json", // relative path
"outputMode": "default", // "default", "apiOnly", "all"
"outputPath": "./SAG" // relative path
}
——Initial Configuration
|Key Name|Value|Description|
|---|---|---|
|inputMode|json| use .json as source|
| |url| user url as source |
|inputPath|./swagger.json|This path is relative path base on your project|
||http://10.100.xxx.x:8080/swagger_doc|url address to get source|
|outputMode|default,-d
--default
|Get: api-config-list.js, index.js, [dependent files]|
|| apiOnly -a
--apiOnly
|Get: index.js, [dependent files]|
||all -A
-all
|[All Generate File](#——All Generate File)|
|outputPath|./SAG|files generate path, default: ./SAG
|
create a swagger-api-config.json
sag init
Then check whether you get this file
Via CLI
sag g
[inputPath]
(required)[outputPath]
(.json or url)<outputMode>
sag g ./swagger.json ./src/api -A
通过在项目路径下的swagger.json文件,在项目路径下src/api文件夹下,生成全部可生成文件
sag g ./swagger.json -a
省略输出路径,使用默认
./SAG
,仅生成index.js
和依赖文件
sag g ./swagger.json ./src/api
省略输出模式
sag g http://~.swagger_doc
省略输出路径和输入模式
File Generate Info
#####——All Generate File
|File Name|Description|
|------------------|---|
|api-config-list.js|SwaggerJson文件源映射成__Js格式的api列表配置文件__,所有api数据/方法的来源,可以读取,再次使用sag g
命令后数组中配置过的api对象仍会保留,但是脚本会将swaggerJson中不存在的api方法会被删除,不要在此文件中添加删除api对象,可配置可选参数。文件详情|
|||
|index.js|所有api调用方法的总线,api请求链路上最后一步执行的函数。文件详情|
|||
|Dependent files|api调用的方法依赖文件,目前包括:[client.js](——Dependent files),[signature.js](——Dependent files),[utils.js](——Dependent files)|
——Dependent files
|File Name|Description| |-----------|---| |client.js|定义全局baseUrl(请求url前缀),封装api请求使用的请求对象,可使用axios, fetch等Js-api请求库| ||| |signature.js|定义api为请求参数生成签名的方法。轻依赖文件,如果你不需要签名功能,可以删除掉本文件| ||| |utils.js|api调用时用到的一些逻辑方法,目前包括: forEach (polyfill)|
File Change Info
第一次使用SAG或者后端更新swaggerJson输入源后,运行
sag g [outputPath] [inputPath] <outputMode>
, SAG将会:
- api-config-list.js:SAG会遍历生成api配置数组,保留配置过的api对象,清除SwaggerJson中不存在的api对象,如果你在此文件中添加了临时的api对象,若在SwaggerJson中不存在,将会被清除,所以
不应该在此文件中添加不存在/不提供的api
- index.js:SAG将生成新的index.js,
用户**在此文件中**的修改/临时添加的api方法将不会保留
- [Dependent files](#####——All Generate File): 所有依赖文件
如果已存在,将使用存在的文件
,SAG不做任何替换
SwaggerJson提供的api与项目的api一一对应,即前端不应该自定义后端不提供的api,但是由于项目开发中前端工作超前于后端,可能需要一些变动的方式
——添加临时/测试api接口
在
本地SwaggerJson输入源
中暂时添加对应格式的api-json对象
"/v1/organizations/{organization_id}/read_details": {
"get": {
"description": "------获取机构阅读信息-------",
"parameters": [{
"in": "formData", // post等方法请求Body中的参数
"name": "timescope",
"type": "string",
"required": false
}, {
"in": "query", // url地址后缀中的参数
"name": "sort_by_read_times",
"type": "string",
"required": false
}, {
"in": "path", // 路径中的参数
"name": "organization_id",
"type": "integer",
"required": true
}],
"tags": ["organizations"],
}
},
上述字段都是SAG运行必须依赖的参数,其他参数你看心情
SwaggerJson Example:
This is a code block generated by grape-swagger
这是一段由后端Ruby grape-swagger插件生成的
api-json文档
, 保存为.json
文件后使用SAG试试
{
"info": {
"title": "projectApi",
"version": "0.0.1"
},
"swagger": "2.0",
"produces": ["application/json"],
"host": "localhost:8080",
"paths": {
"/v1/users/{user_id}/profile": {
"get": {
"summary": "------获取用户信息--------",
"description": "------获取用户信息--------",
"produces": ["application/json"],
"parameters": [{
"in": "path",
"name": "user_id",
"description": "user id",
"type": "string",
"required": true
}],
"responses": {
"200": {
"description": "------获取用户信息-------"
}
},
"tags": ["users"],
"operationId": "getV1UsersUserIdProfile"
}
},
"/v1/auth/sms/code": {
"post": {
"summary": "-------send sms code----------",
"description": "-------send sms code----------",
"produces": ["application/json"],
"consumes": ["application/json"],
"parameters": [{
"in": "formData",
"name": "phone",
"description": "phone number",
"type": "string",
"required": true
}, {
"in": "formData",
"name": "channel",
"description": "channel",
"type": "string",
"enum": ["web", "ios"],
"required": true
}, {
"in": "formData",
"name": "action",
"type": "string",
"enum": ["register", "reset"],
"required": true
}],
"responses": {
"201": {
"description": "-------send sms code----------"
}
},
"tags": ["auth"],
"operationId": "postV1AuthSmsCode"
}
},
"/v1/search_tips": {
"get": {
"summary": "------获取搜索信息-------",
"description": "------获取搜索信息-------",
"produces": ["application/json"],
"parameters": [{
"in": "query",
"name": "keyword",
"description": "关键词",
"type": "string",
"required": true
}],
"responses": {
"200": {
"description": "------获取搜索信息-------"
}
},
"tags": ["search_tips"],
"operationId": "getV1SearchTips"
}
}
}
}