文章目录
  1. 1. 动机
  2. 2. Swagger 简介
    1. 2.1. info
    2. 2.2. definitions
    3. 2.3. paths
  3. 3. swagger-ts-doc 中类和方法
    1. 3.1. apiModelProperty 装饰器
    2. 3.2. Request参数
    3. 3.3. Reponse
    4. 3.4. registerRequestMapping 方法
  4. 4. 结束

项目地址:https://github.com/wz2cool/swagger-ts-doc
demo代码地址:https://github.com/wz2cool/swagger-ts-doc-demo

动机

Swagger API 文档框架相信大家都使用过,并且真的很方便,但是大家应该都是用框架生成的出来swagger 文档,可能很少人会去写 yaml文档吧。
确实我在使用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中的一个类。

1
2
3
4
5
6
7
8
9
10
11
12
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 描述(这里我们不使用yaml语法,使用的json 语法)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
"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)

Reponse

参考swagger 文档:
https://swagger.io/docs/specification/describing-responses/
我们看一下定义多个返回相应

1
2
3
4
5
[
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节点调用的方法,这里我们举一个修改学生的一个例子。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 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 并提出宝贵的意见。

文章目录
  1. 1. 动机
  2. 2. Swagger 简介
    1. 2.1. info
    2. 2.2. definitions
    3. 2.3. paths
  3. 3. swagger-ts-doc 中类和方法
    1. 3.1. apiModelProperty 装饰器
    2. 3.2. Request参数
    3. 3.3. Reponse
    4. 3.4. registerRequestMapping 方法
  4. 4. 结束