swaggered CLI：swagger json schema 转成 TS 代码

JavaScript与编程艺术
314 阅读3分钟

💢 背景或痛点

和服务端联调接口，一般都是先给 swagger 文件，前端粘贴到 editor.swagger.io/ 然后从入参到出参逐个字段复制粘贴其描述当做注释、人工推断类型生成 TS，最后手写成 Service 层代码共 view 调用。

整个过程不仅耗时而且易出错，要是能有个 cli 工具自动生成 Service 层代码就好了。

生成效果大概如下：

/** Comment about this service from schema description */
export const JobService = {
  // 🔥 Grouped by path or tag, nicely organized. Give it a try by passing the `grouped` flag
  prefix: '/api/model/v1/evaluate/job',

  /**
   * Comment about getJobDetail
   */
  async getJobDetail(params: IGetJobDetailParams) {
    return request<Data<IGetJobDetailRespData>>(`${this.prefix}/${params.jobId}`, {
      method: 'GET',
    });
  },

  /**
   * Comment about createJob
   */
  async createJob(data: ICreateJobReqData) {
    return request<Data<ICreateJobRespData>>(this.prefix, {
      method: 'POST',
      data: ICreateJobReqData
    });
  },

  /**
   * Comment about stopJob
   */
  async stopJob(params: IStopJobParams) {
    return request<Data<IStopJobRespData>>(`${this.prefix}/${params.jobId}`, {
      method: 'POST',
    });
  },
};

// 🔥 Generate **Generic Response Type** from parsing your response structure intelligently!
type Data<T> = {
  code: number;
  data: T;
  message: string;
}

interface IGetJobDetailParams { ... }
interface IGetJobDetailRespData { ... }
// ... other types omitted

市面上的我都试过没法生成这么满足个人诉求的，故开发了一个“从 Swagger JSON Schema 生成 TypeScript 客户端请求代码并带有严格的 TS 类型和丰富的注释”的 CLI 工具 swaggered。

✨ 特点

  • 严格的 TS 类型：生成带有严格 TS 类型的客户端代码，字段描述通过 tsdoc 方式保留。
  • 可过滤：可通过按 API 路径和 HTTP 方法进行过滤，只生成你需要的部分。
  • 灵活使用：可以通过 CLI 或编程方式使用。
  • 灵活的格式：
    • 可仅生成类型或函数
    • 按路径或标签自动分组。让代码组织结构更优。🔥
    • 通过智能解析你的响应结构，生成通用响应类型！🔥
  • 美化输出 💅：使用 shikijs 高亮输出内容。
  • 经实战测试：支持所有 Swagger OpenAPI 版本以及从 v16 到 v22 的 Node.js。
  • 单元测试：使用 Node.js 内置单测和覆盖率统计 node --test --experimental-test-coverage

📀 使用

详见 www.npmjs.com/package/swa…

image-92.png

图来自 https://apifox.com/apiskills/introduction-to-swagger-ui-3/

🔬 实现原理

关键依赖库：

image-87.png

开发特点

尽量使用最新 Node.js 特性而非依赖三方库。

  • mjs + tsdoc：使用纯 JS，无编译所见即所得更容易调试（虽目前 TS 可被 Node.js 执行，但 node_modules 尚未支持，后续若支持可改成纯 TS）。
  • 无三方测试框架：Node.js 内置测试框架和覆盖率。
  • 无三方参数解析库（如 yargs）：使用内置 Node.js parseArgs。
  • 不依赖发布工具：通过 npm script hooks 实现自动发布流程。
  • 使用 import attributes json 提高文件解析安全性。

👨‍💻 代码流程图

关键伪代码

graph TD
    A[generateTSFromFile] --> B[readJSONFile]
    B --> C[generateTSFromSchema]
    C --> D{filterSchema api/reg/method}
    D -->|Yes| E[generateTS]
    D -->|No| F[End]

    E --> E1[dereference: await RefParser.dereference jsonSchema]
    E1 --> E2[removePropertyTitle json-schema-traverse]
    E2 --> E3[compileSwaggerJSON]
    E3 --> E4[for each of item]
    E4 --> E5[preProcess]
    E5 --> E5a[extract summary]
    E5 --> E5b[extract parameters and normalize to schema]
    E5 --> E5c[extract request data and normalize to schema]
    E5 --> E5d[extract response body and normalize to schema]
    %% E4 --> E6[compile]
    E5a --> E6[compile]
    E5b --> E6[compile]
    E5c --> E6[compile]
    E5d --> E6[compile]
    E6 --> E6a[gen parameters interface]
    E6 --> E6b[gen requestData interface]
    E6 --> E6c[gen responseBody interface]
    E6 --> E6d[gen genericResp interface]
    E6 --> E6e[extract group label from tags]
    E6a --> E6f[gen code]
    E6b --> E6f[gen code]
    E6c --> E6f[gen code]
    E6d --> E6f[gen code]
    E6e --> E6f[gen code]

    E6f --> G[postProcess]
    G --> G1[addPrefixToInterface]
    G --> G2[removeExport]

    G1 --> H[prettyPrint]
    G2 --> H[prettyPrint]
    H --> H1[printCodeByGroup]
    H1 --> H1a[groupBy groupLabel]
    H1 --> H1b[toServiceName]
    H1 --> H1c[extract common api prefix]
    H --> H2[printTypes]
    H2 --> H3[print highlighted code using shiki]
    H1a --> H3[print highlighted code using shiki]
    H1b --> H3[print highlighted code using shiki]
    H1c --> H3[print highlighted code using shiki]
avatar
文章
阅读
粉丝