生成 API 文档

TSRPC 支持一键生成 Swagger/OpenAPI、Markdown 等多种格式的文档。

生成文档

在后端项目下运行 npm run doc 即可生成接口文档。

cd backend
npm run doc

• 默认生成到 backend/docs，也可在 tsrpc.config.ts 中修改相关配置。
• 将生成 2 个文件，对应 2 种不同格式，可根据实际需要选用。
  • openapi.json Swagger / OpenAPI 3.0 格式
    • 可以直接导入现有的各种工具中使用
  • tsapi.md Markdown 格式
    • 适用于代码仓库或云文档展示，以 TypeScript 类型展示数据结构
    • 数据结构显示为展平引用和继承关系后的最终类型

提示

想要通过云文档分享，可在 VSCode 中打开 Markdown 的预览模式，然后全选预览部分复制到云文档，如此复制过去的将是带格式的文本而非 Markdown 源码。

文档注释

你可以在协议上直接编写前置注释，注释将被作为描述信息被生成到文档中。

• 以 /** */ 格式编写前置注释，内容支持 Markdown
• 接口信息在 请求类型 定义前编写前置注释
• 字段信息在字段定义前编写前置注释
• 前置注释的第一行将作为字段/接口名称，后续行作为字段/接口说明

例如：

/**
 * 获取商品列表 -----（接口名称）
 * 分页获取商品列表，单次请求最多获取 100 条记录。 ----- （接口描述）
 */
export interface ReqGetProductList {
    /**
     * 当前页码 ----- （字段名称）
     * 从 1 开始，默认为 1 ----- （字段描述）
     */
    current?: number,
    /**
     * 分页大小
     * 默认为 20
     */
    pageSize?: number
}

export interface ResGetProductList {
    /** 商品列表 */
    list: {
        /** 商品名称 */
        name: string,
        /** 商品价格 */
        price: number
    }[]
    /** 总记录条数 */
    total: number
}

效果示例

飞书文档

（从 Markdown 预览内容复制）

ApiFox

（OpenAPI 格式导入）