项目地址：https://github.com/wz2cool/swagger-ts-doc
demo代码地址：https://github.com/wz2cool/swagger-ts-doc-demo
动机
Swagger API 文档框架相信大家都使用过，并且真的很方便，但是大家应该都是用框架生成的出来swagger 文档，可能很少人会去写 yml或者json文档吧。
确实我在使用nodejs 发现写接口还是很方便，但是唯独在写swagger文档时候发现nodejs中的框架并不好用，曾经用过swagger-jsdoc,写了一堆注释，然后自己崩溃了。
好歹我自己也写了快2年的java了，为什么不照着java的方式写一套呢，于是写了 swagger-ts-doc，自用下来还是挺方便的。
Swagger 简介
大家可打开一下 http://editor.swagger.io/ 看一下官方写的一个例子。
info
这个应该是一些对这个文档的描述信息，这个在swagger-ts-doc 是可以配置的, 对应的配置为 SwaggerInfoProperty。
definitions
这个是一个重要的节点，这个节点其实是定义了我们所有的类，比如有个requestBody 其实是一个类，就可以通过 $ref: "#/definitions/User" 进行关联。
在swagger-ts-doc 中，这里的是通过apiModelProperty进行描述的
paths
这个节点就是最重要的节点，它描述了我们所有路由post,get,put,delete.
在swagger-ts-doc 中，这里是通过registerRequestMapping 进行描述的。
swagger-ts-doc 中类和方法
apiModelProperty 装饰器
这个装饰器主要是为了生成 definitions 中的model，我们看代码可看到如何描述一个typescript中的一个类。
import { apiModelProperty, DataType } from "swagger-ts-doc";
export class UpdateStudentDto {
@apiModelProperty(
DataType.STRING, // 类型
false, // 是否必填
"学生姓名" // 描述
)
public name: string;
@apiModelProperty(DataType.INTEGER, false, "学生年龄")
public age: number;
}
最后会生成与之对应的swagger json 描述（这里我们不使用yml语法，使用的json 语法）
"UpdateStudentDto": {
"type": "object",
"required": ["name", "age"],
"properties": {
"name": {
"type": "string",
"description": "学生姓名"
},
"age": {
"type": "integer",
"description": "学生年龄"
}
}
},
Request参数
参考swagger 文档：
https://swagger.io/docs/specification/describing-parameters/
https://swagger.io/docs/specification/describing-request-body/
- RequestBody 类对应文档 requestBody
- PathVariable 类对应文档 path parameters （in: path)
- RequestParam 类对弈文档 query parameters （in: query)
Response
参考swagger 文档：
https://swagger.io/docs/specification/describing-responses/
我们看一下定义多个返回相应
[
new Response(HttpStatusCode.OK, DataType.STRING, "ok"),
new Response(HttpStatusCode.INTERNAL_SERVER_ERROR, DataType.STRING, "内部错误"),
new Response(HttpStatusCode.NOT_FOUND, DataType.STRING, "学生未找到"),
],
registerRequestMapping 方法
这里就是我们要去生成swagger中paths节点调用的方法，这里我们举一个修改学生的一个例子。
registerRequestMapping(
StudentApi, // tags 类似于把一些路由放到一个组里面
"/students/{id}", // 路由
RequestMethod.PUT,
[
new PathVariable("id", DataType.STRING, "学生ID"),
new RequestBody("student", DataType.OBJECT, UpdateStudentDto, "学生"),
],
[
new Response(HttpStatusCode.OK, DataType.STRING, "ok"),
new Response(HttpStatusCode.INTERNAL_SERVER_ERROR, DataType.STRING, "内部错误"),
new Response(HttpStatusCode.NOT_FOUND, DataType.STRING, "学生未找到"),
],
"修改学生"); // 对这个路由的描述
route.put("/:id", (req, res, next) => {
const input = req.body;
const id = req.params.id;
if (!id) {
res.status(HttpStatusCode.INTERNAL_SERVER_ERROR);
res.json("学生ID不能为空");
return;
}
if (lodash.findIndex(this.students, (x) => x.uuid === id) < 0) {
res.status(HttpStatusCode.NOT_FOUND);
res.json(`未能找到学生`);
return;
}
const student = new Student();
student.uuid = id;
student.name = input.name;
student.age = input.age;
this.modifyStudent(student);
res.json("ok");
});
我们最后看一下效果
结束
利用typescript 现在我们可以轻松用强类型来写swagger文档了，swagger-jsdoc 虽然很好但是写起来太痛苦了，希望大家可以关注swagger-ts-doc 并提出宝贵的意见。