利用typescript生成Swagger文档
2018-04-14 19:17
357 查看
项目地址:https://github.com/wz2cool/swagger-ts-doc
demo代码地址:https://github.com/wz2cool/swagger-ts-doc-demo
确实我在使用nodejs 发现写接口还是很方便,但是唯独在写swagger文档时候发现nodejs中的框架并不好用,曾经用过swagger-jsdoc,写了一堆注释,然后自己崩溃了。
好歹我自己也写了快2年的java了,为什么不照着java的方式写一套呢,于是写了 swagger-ts-doc,自用下来还是挺方便的。
在swagger-ts-doc 中,这里的是通过apiModelProperty进行描述的
在swagger-ts-doc 中,这里是通过registerRequestMapping 进行描述的。
最后会生成与之对应的swagger json 描述(这里我们不使用yml语法,使用的json 语法)
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)
https://swagger.io/docs/specification/describing-responses/
我们看一下定义多个返回相应
我们最后看一下效果
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 并提出宝贵的意见。相关文章推荐
- ,有一款RESTFUL接口的文档在线自动生成+功能测试功能软件——Swagger UI,具体配置过程可移步《Spring Boot 利用 Swagger 实现restful测试》
- 利用Swagger Maven Plugin生成Rest API文档
- 利用Swagger生成Rest API文档
- spring boot利用swagger和spring doc生成在线和离线文档
- 利用Swagger Maven Plugin生成Rest API文档
- VS2010/MFC编程入门之二(利用MFC向导生成单文档应用程序框架)
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- ASP.NET Web API 使用Swagger生成在线帮助测试文档
- Swagger生成API文档
- 利用xcode自动生成项目文档
- Swagger生成WebAPI文档
- asp.net core 使用 swagger 生成接口文档
- java利用freemarker生成简单格式的word文档
- 利用PDFLib生成PDF文档
- 利用PDFLib生成PDF文档
- ASP.NET Web API 使用Swagger生成在线帮助测试文档
- 一款RESTFUL接口的文档在线自动生成+功能测试功能软件——Swagger简介
- swagger生成API文档
- 【工具篇】利用DBExportDoc V1.0 For MySQL自动生成数据库表结构文档(转
- linux下利用apigen自动生成接口文档