swagger与JSDoc的集成实践

前言

上次分享了一篇基于TypeScript的JSDoc注释后，我一直在想一件事情：

如何用JSDoc来便利我们的前端开发？

虽然我们现在日常开发中使用的是JavaScript，但是TypeScript带来的类型系统的便利性已经是有目共睹的了。但是，原有的项目受限于排期，想要整体迁移到TypeScript还是比较困难。

但如果在当前的JavaScript项目中，如果可以通过JSDoc，在JavaScript中引入对于一部分代码的类型定义和代码提示，想必也是极好的。

Web开发中很多时候都涉及到接口的联调，前后端联调可以说是一项无比重要但绝对繁琐枯燥的工作。每次联调的时候，都类似这样：

所以我在想：如果能够做到如下这些，是否就能优化接口联调的体验：

• 如果能够自动去生成request/response，是不是能够减少重复的人工和避免出错？
• 后端定义好的数据类型/枚举等等，如何在前端直接去使用？
• 如何去自动化创建Mock数据，优化开发流程？

既然想到了，那就不妨开始干吧。

技术调研

Swagger

关于Swagger, 做过前后端开发的应该都不陌生。Swagger和后端常用的开发框架中，例如Spring Boot或者Nest.js等都有很好的集成支持，通过在后端项目中集成Swagger，我们可以很方便的提供一个可视化的在线API文档工具，来方便接口联调的开展。

Swagger-UI

关于Swagger-UI，想必大家都不陌生；这其实就是Swagger的可视化、可交互的API资源。它通过OpenAPI规范自动生成，便利了后端API文档化和前端使用API数据。

OpenAPI

OpenAPI Specification，其实也就是Swagger，提供了Restful APIs的标准，当前有v2和v3两个版本。官方网站上是这样介绍的：

the industry standard for RESTful API design

打开Swagger-UI页面的控制台，我们可以看到它发出了一条类似这样的请求：

这个请求就是去获取对应的API配置信息，请求的响应如下：

其中重要的有两部分：

• definitions: 在paths中使用到的部分自定义的对象的定义信息，包括具体的数据类型等等
• paths: 关于请求的路径信息，包括请求的方法、路径名、请求参数、请求/响应数据类型、响应类型等等 关于Open API的更多信息，可以在这里查阅。

实现

既然已经调研并了解了JSDoc和Swagger，那接下来就可以开始实现了。

目标

1. 根据paths提供的信息，自动生成接口的request/response文件
2. 根据后端定义的enum，生成前端需要用到的枚举
3. 根据response生成对应的mock数据

最终成果

生成的Axios请求service

请求一下：

使用响应：

再看看VS Code的代码注释

枚举

/**
 * 文件类型
 * @readonly
 * @enum
 * @property {string} swagger_enum_354c1eca783d88caad75e4831555b334.Image - 图片
 * @property {string} swagger_enum_354c1eca783d88caad75e4831555b334.Video - 视频
 * @property {string} swagger_enum_354c1eca783d88caad75e4831555b334.Voice - 音频
 * @property {string} swagger_enum_354c1eca783d88caad75e4831555b334.Attachment - 附件
 */
export const swagger_enum_354c1eca783d88caad75e4831555b334 = {
  /** 图片 */
  Image: 1,
  /** 视频 */
  Video: 2,
  /** 音频 */
  Voice: 3,
  /** 附件 */
  Attachment: 4,
}

mock数据

export default {
  "GET /departmentprojectref/{id}": {
    "code": 200,
    "data": {
      "createTime": "string",
      "departmentId": 1,
      "id": 1,
      "modifyTime": "string",
      "projectId": 1
    },
    "message": "string",
    "traceId": "string"
  },
  "PUT /departmentprojectref/{id}": {
    "code": 200,
    "data": {
      "createTime": "string",
      "departmentId": 1,
      "id": 1,
      "modifyTime": "string",
      "projectId": 1
    },
    "message": "string",
    "traceId": "string"
  },
  "DELETE /departmentprojectref/{id}": {
    "code": 200,
    "message": "string",
    "traceId": "string"
  }
}

再进一步

到这里，还有一点问题：

• service/enum的名称都是自动生成的，缺乏易读性
• 生成的文件需要写入到对应路径下

这里，结合umi plugin和umi ui，开发了umi-plugin-swagger-doc，实现了上述功能：

差不多就这样了~

参考链接

• Swagger
• 基于TypeScript的JSDoc注释
• swagger-to-jsdoc
• umi-plugin-swagger-doc