qianmi-egg-swagger
v0.1.3
Published
针对ts类型的eggjs项目自动生成swagger的接口文档插件
Downloads
1
Maintainers
Readme
ts-egg-swagger插件
目标
让 基于typescript的eggjs项目可以像 javaBFF 一样,通过约定配置,就可以生成swagger接口文档。
目录结构
.
├── lerna.json
├── package.json
├── packages
│ ├── egg-example-------插件使用demo
│ └── egg-swagger-------egg-swagger插件
└── readme.md
配套使用的vscode代码提示插件 egg-code-prompt https://github.com/JustinYi922/egg-code-prompt
插件原理
- 解析路由,可以知道有多少请求
- 解析 controller目录下面的所有类来获取模块
- 解析controller对应的目录typings下的custom下的相同名称的.d.ts 的声明文件(另外typings下面的common.d.ts存放公共的类型信息)
- 生成 swagger 的 openApi 规范 json 文件
- 保存到本地或上传 Yapi
怎么使用
- 下单插件
npm install qianmi-egg-swagger --save-dev
- 配置插件
建议是写在 package.json 的 scripts.postpublish 里面
用swagger-ui生成在线文档
"ui": "./node_modules/.bin/qm-egg-doc swagger-ui"
发布到指定的yapi
"doc": "./node_modules/.bin/qm-egg-doc --yapi <这里yapi的post请求地址>"
swagger 规范
https://swagger.io/specification/v2/
怎么使用?
路由
规则:http 请求+url+controller 路径+方法
//模拟get请求 path
router.get(
"/delivery/address/list/:phonenum",
controller.deliveryAddress.addressList
);
//模拟get请求 query
router.get("/delivery/address/update", controller.deliveryAddress.update);
//模拟post请求
router.post("/delivery/address/add", controller.deliveryAddress.add);
//模拟all请求
router.all("/delivery/address/delete", controller.deliveryAddress.delete);
controller
import { Controller } from 'egg';
/**
* 配送管理
*/
export default class DeliveryAddress extends Controller {
/**
* 方法名称
* @path phonenum string 手机号
*/
public async addressList() {
this.ctx.response.success(null);
}
/**
* 方法名称
* @query province string 省 required
* @query city string 市 required
* @query area string 区
*/
public async update() {
this.ctx.response.success(null);
}
/**
* 方法名称
* @request IAddressAddParam
*/
public async add() {
this.ctx.response.success(null);
}
/**
* 方法名称
* @response AddressDTO
*/
public async delete() {
this.ctx.response.success(null);
}
/***
* 方法名称
* @response IBaseDTO<ICityDelivery>
*/
public async cityDeliveryAddress() {
this.ctx.response.success(addressList);
}
}
声明文件
declare module 'shop' {
interface IAddressAddParam {
/**
* 手机号码
*/
mobile: string;
receiptUserMobile: string;
receiptUserName: string;
address: string;
/**
* 经度纬度
*/
latitude: number;
longitude: number;
/**
* 地址备注
*/
addressRemark?: string;
/**
* 是否默认
*/
isDefault?: boolean;
}
interface AddressDTO{
/**
* 手机号码
*
*/
mobile: string;
receiptUserMobile: string;
receiptUserName: string;
address: string;
/**
* 经度纬度
*/
latitude: number;
longitude: number;
/**
* 地址备注
*/
addressRemark?: string;
/**
* 是否默认
*/
isDefault?: boolean;
}
}
注意
- 生成接口文档,技术只是实现而已,最重要的是约定和完善接口信息
- 文件名如果有多个单词,请以英文-分割
- 代码中路径和关键词等命名请用驼峰的形式
- 请把 typings/custom 文件下的路径和名称与 controller 下面的文件的路径保持一致
不足
- 还有很多功能未实现;
- 暂未支持直接访问 swagger 页面
- 如有 bug 请及时告知,或者一起修改一下哈
- 返回值是基本类型处理