🎯 详细 JSDoc 注释生成指南

本指南详细说明如何从 OpenAPI 文档生成包含完整类型信息和描述的 JSDoc 注释。

✨ 功能特点

1. 自动提取参数信息

生成器会从 parameters 中提取：

• 参数名
• 参数类型（schema.type）
• 参数描述（description）
• 是否必填（required）

示例：

parameters:
  - name: page
    in: query
    description: 页码
    required: false
    example: 1
    schema:
      type: integer
  - name: pageSize
    in: query
    description: 每页数量
    required: false
    example: 10
    schema:
      type: integer

生成的注释：

/**
 * @param {Object} params 请求参数
 * @param {integer} params.page (可选) 页码
 * @param {integer} params.pageSize (可选) 每页数量
 */

2. 详细返回值类型

生成器会递归解析 responses['200'].schema.properties.data 的结构，包括：

• 基本类型（string, integer, boolean, number）
• 嵌套对象
• 数组类型（Array<>）
• 每个字段的描述

示例：

responses:
  '200':
    content:
      application/json:
        schema:
          properties:
            data:
              properties:
                user:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: 用户ID
                    name:
                      type: string
                      description: 姓名
                list:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: ID
                      title:
                        type: string
                        description: 标题

生成的注释：

/**
 * @returns {Promise<{
 *   code: number; // 状态码
 *   msg: string; // 消息
 *   data: {
 *     user: {
 *       id: integer; // 用户ID
 *       name: string; // 姓名
 *     };
 *     list: Array<{
 *       id: integer; // ID
 *       title: string; // 标题
 *     }>;
 *   };
 * }>}
 */

📋 完整示例

输入：OpenAPI 文档

# 获取订单列表

## OpenAPI Specification

\```yaml
openapi: 3.0.1
info:
  title: ''
  version: 1.0.0
paths:
  /srv/:
    get:
      summary: 获取订单列表
      description: 分页获取用户的订单列表
      tags:
        - 订单管理
      parameters:
        - name: f
          in: query
          example: behalo
        - name: a
          in: query
          example: order_list
        - name: page
          in: query
          description: 页码
          example: 1
          schema:
            type: integer
        - name: pageSize
          in: query
          description: 每页数量
          example: 10
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 0=失败，1=成功
                  msg:
                    type: string
                    description: 错误信息
                  data:
                    type: object
                    properties:
                      list:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: 订单ID
                            order_no:
                              type: string
                              description: 订单号
                            status:
                              type: string
                              description: 订单状态
                            total_amount:
                              type: number
                              description: 订单金额
\```

输出：生成的 API 文件

import { fn, fetch } from '@/api/fn';

const Api = {
  GetList: '/srv/?a=order_list',
}

/**
 * @description: 获取订单列表
 * @param {Object} params 请求参数
 * @param {integer} params.page (可选) 页码
 * @param {integer} params.pageSize (可选) 每页数量
 * @returns {Promise<{
 *   code: number; // 状态码
 *   msg: string; // 错误信息
 *   data: {
 *     list: Array<{
 *       id: integer; // 订单ID
 *       order_no: string; // 订单号
 *       status: string; // 订单状态
 *       total_amount: number; // 订单金额
 *     }>;
 *   };
 * }>}
 */
export const getListAPI = (params) => fn(fetch.get(Api.GetList, params));

🎨 类型映射

OpenAPI 类型 → JavaScript 类型

OpenAPI 类型	JavaScript 类型	说明
string	string	字符串
integer	integer	整数
number	number	数字
boolean	boolean	布尔值
array	Array<>	数组
object	{}	对象

特殊类型处理

1. 嵌套对象：

   user:
    type: object
    properties:
      id:
        type: integer
   

   生成：

   user: {
    id: integer;
   };
   

2. 对象数组：

   list:
    type: array
    items:
      type: object
      properties:
        id:
          type: integer
   

   生成：

   list: Array<{
    id: integer;
   }>;
   

3. 基本类型数组：

   tags:
    type: array
    items:
      type: string
   

   生成：

   tags: Array<string>;
   

📝 最佳实践

1. 完善描述信息

确保为每个字段添加 description：

parameters:
  - name: userId
    description: 用户ID  ✅ 添加描述
    schema:
      type: integer

2. 明确类型定义

始终指定 schema.type：

schema:
  type: integer  ✅ 明确类型

3. 标记必填字段

使用 required 标记必填参数：

parameters:
  - name: id
    required: true  ✅ 标记为必填
    schema:
      type: integer

4. 使用有意义的字段名

字段名应该清晰表达含义：

properties:
  user_id:  ✅ 清晰
    type: integer
  id:      ❌ 不明确
    type: integer

🔧 高级用法

多层嵌套对象

data:
  properties:
    user:
      type: object
      properties:
        profile:
          type: object
          properties:
            avatar:
              type: string
              description: 头像URL

生成：

data: {
  user: {
    profile: {
      avatar: string; // 头像URL
    };
  };
};

混合类型数组

items:
  type: object
  properties:
    id:
      type: integer
    name:
      type: string
    tags:
      type: array
      items:
        type: string

生成：

Array<{
  id: integer;
  name: string;
  tags: Array<string>;
}>

⚠️ 注意事项

1. description 优先级：优先使用 description，其次使用 title
2. 空描述处理：如果字段没有描述，会生成空注释
3. 嵌套深度：支持任意深度的嵌套对象
4. 参数过滤：a 和 f 参数不会出现在 @param 中
5. 类型大小写：OpenAPI 的 integer 会保留（不是 number）

🚀 开始使用

1. 在 OpenAPI 文档中添加完整的 description 和 type
2. 运行 pnpm api:generate
3. 查看生成的详细 JSDoc 注释
4. 在 IDE 中享受智能提示和类型检查！

📚 相关文档

• OpenAPI 规范官方文档
• JSDoc 官方文档
• 详细使用指南