利用typescript生成Swagger文档
项目地址: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 并提出宝贵的意见。
利用typescript生成Swagger文档的更多相关文章
- 黄聪:利用OpenXml生成Word2007文档(转)
原文:http://blog.csdn.net/francislaw/article/details/7568317 版权声明:本文为博主原创文章,未经博主允许不得转载. 目录(?)[-] 一Op ...
- 利用OpenXml生成Word2007文档
一.OpenXml简介 利用C#生成Word文档并非一定要利用OpenXml技术,至少可以使用微软提供的Office相关组件来编程,不过对于Office2007(确切的说是Word.Excel和Pow ...
- asp.net core web api 生成 swagger 文档
asp.net core web api 生成 swagger 文档 Intro 在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果 ...
- qt 利用 HTML 生成PDF文档,不能显示jpg图片
利用 QPrinter 和html 生成 pdf文档 其中用html语句有显示图片的语句 但只能显示png格式的图片,不能显示jpg格式图片. 经过排查:语法,文件路径等都正确,最终在stack ov ...
- asp.net core 2.1 生成swagger文档
新建asp.netcore2.1 api项目 “WebApplication1” 在nuget管理器中添加对Swashbuckle.AspNetCore 3.0.0.Microsoft.AspNetC ...
- 利用ItextSharp 生成PDF文档改进版
导入的ItextSharp.dll一定要是较高的版本 数据库表结构 生成的PDF样式 代码: namespace WebPDF { public partial class _Default : Sy ...
- 利用NPOI生成word文档(c#)
WordTest.aspx.cs using System; using System.IO; using System.Text; using System.Web; using System.We ...
- 利用NPOI生成DOCX文档
首先安装NPOI控件: Install-Package NPOI 代码: using NPOI.OpenXmlFormats.Wordprocessing; using NPOI.XWPF.UserM ...
- 浅析如何在Nancy中使用Swagger生成API文档
前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document.但是还有许许多多的不足. 为了能稍微完善一下这个Document,这篇引用了当前流行的Swagger, ...
随机推荐
- java编程基础知识及常见例题
⒈标识符: 只能包含数字.字母.下划线.$,并且不能以数字开头.语义直观规范 驼峰法则: 如:方法名.变量名采用驼峰法则 帕斯卡命名法: 如: 类.接口.枚举采用帕斯卡命名法包名:网址倒写,com.网 ...
- zip详解
http://www.360doc.com/content/06/0915/14/10610_208147.shtml
- 以太坊开发DApp入门教程——区块链投票系统(一)
概述 对初学者,首先要了解以太坊开发相关的基本概念. 学习以太坊开发的一般前序知识要求,最好对以下技术已经有一些基本了解: 一种面向对象的开发语言,例如:Python,Ruby,Java... 前 ...
- 借鉴别人的Oracle 11g安装和卸载图文教程
Oracle 11g安装 1.解压下载的包,然后进入包内,点击setup.exe开始安装 . 2.出现如下:一般把那个小对勾取消,点击下一步进行, 弹出下图这个后点‘是' 3.下图后,选择创建和配置数 ...
- NVisionXRFBXConverter(Beta版)实践课程
一.前言 NVisionXR引擎使用的模型格式为.mesh(具体请看NVisionXR引擎基本介绍:http://www.arvrschool.com/read-7381 ),为了能够将常见的格式转换 ...
- C语言助教批改
作业批改 每次作业批改后写一篇作业点评,助教轮流写作业总结.(总结分工老师安排). 每个助教点评自己负责的同学博客,点评要详细,不能只有一句话. 有比较优秀博客请或典型问题推荐到qq群,并发给写总结助 ...
- 201621123062《java程序设计》第八周作业总结
1. 本周学习总结 以你喜欢的方式(思维导图或其他)归纳总结集合相关内容. 思维导图: 2. 书面作业 2.1ArrayList代码分析 2.1.1 解释ArrayList的contains源代码 源 ...
- 201621123060《JAVA程序设计》第二周学习总结
1.本周学习总结 本周学习了JAVA中的引用类.包装类(学习了一种语法:自动装箱)和数组(遍历数组的新方法foreach循环). 2. 书面作业 1.String-使用Eclipse关联jdk源代码 ...
- mysql基础篇 - SELECT 语句详解
基础篇 - SELECT 语句详解 SELECT语句详解 一.实验简介 SQL 中最常用的 SELECT 语句,用来在表中选取数据,本节实验中将通过一系列的动手操作详细学习 SELEC ...
- servlet线程同步问题-代码实现同步(转)
从servlet的生命周期中,我们知道,当第一次访问某个servlet后,该servlet的实例就会常驻 内存,以后再次访问该servlet就会访问同一个servlet实例,这样就带来多个用户去访问一 ...