中间层接口文档

基于AST的Nestjs文档生成解析器，配合vitepress能够进行更自动化，更高效，更美观的文档展示。

安装

npm install nest-ast-docutil

使用方式

• 在项目根目录创建 doc-config.json 配置文件
• package.json 添加开发和编译脚本: zdoc dev & zdoc build

代码编写规范

解析器会自动读取项目下的所有 *.controller.ts 文件进行文档的生成，所以controller内接口需定义请求体和返回体

解析器支持 @nestjs/swagger 的注解规范：

• 读取@ApiOperation内容，作为当前接口的标题(summary)和描述(description)
• 读取@ApiBody内容，作为当前接口返回的数据类型(type)
• 读取函数入参 @Body()的类型定义，作为接口的入参数据类型

类型定义规范

类型的整体定义支持jsdoc的注释方式，并且目前只针对如下tag:

export interface CareCabinInput {
  // aaaa 注释
  aaa: string;
  /**
   * bbbbb 注释
   * 多行注释 bbbbb
   */
  bbb: string;
  /**
   * @description cccc 注释描述
   * @default ccc
   * @require true
   */
  ccc: number[];
}

在不存在tag的情况下，会读取单行或者多行作为当前类型的注释文本。 存在对应tag时，可设置：描述-->@description、默认值-->@default、是否必须-->@require

如果类型定义为 class 类型，则也支持 @nestjs/swagger注释方式

export class QueryDto {
  @ApiProperty({
    description: 'aaaa 类型说明文字',
    default: 'aaaa',
    required: false
  })
  aaa: string;
  /**
   * @description bbbb 类型说明文字
   * @default bbbb
   * @require true
   */
  bbb: string;
}

读取 @ApiProperty 内字段作为类型定义的说明：描述-->description、默认值-->default、是否必须-->required

doc-config.json 配置

{
  "devServer": {
    "base": "./app",
    "glob": ["**/*.controller.ts", "**/dto/*.ts"]
  },
  "nav": [
    {
      "entry": "./apps/projectA/src",
      "text": "ProjectA接口列表",
      "key": "projecta"
    },
    {
      "entry": "./apps/projectB/src",
      "text": "ProjectB接口列表",
      "key": "projectb"
    }
  ],
  "homeLink": {
    "brand": "",
    "alt": ""
  }
}

devServer: zdoc dev 开发环境下，监听的文件基础路径以及对应的文件 nav: 不同项目分类配置，配置项目 entry、text & key homeLink: 文档首页的 按钮链接地址，brand无需配置，alt设置需要跳转的链接