typed-openapi项目新增请求格式支持功能解析

typed-openapi项目新增请求格式支持功能解析

typed-openapi Generate a headless Typescript API client from an OpenAPI spec 项目地址: https://gitcode.com/gh_mirrors/ty/typed-openapi

在API开发领域，类型安全的OpenAPI工具链正变得越来越重要。typed-openapi作为一个优秀的TypeScript OpenAPI工具，近期通过社区贡献新增了对请求格式(requestFormat)的支持功能，这为开发者提供了更完善的类型安全保证。

功能背景

在RESTful API设计中，不同的端点(Endpoint)可能采用不同的请求体编码格式。常见的有：

• application/json (JSON格式)
• application/x-www-form-urlencoded (表单URL编码格式)
• multipart/form-data (多部分表单格式)

typed-openapi原本能够完美处理响应类型和请求参数的类型安全，但缺少对请求格式的明确声明。这可能导致开发者在使用生成的客户端时需要额外查阅文档或源代码才能确定正确的请求格式。

实现方案

新增功能通过分析OpenAPI规范中的requestBody.content字段，自动推断并生成对应的请求格式类型。具体实现逻辑如下：

1. 当检测到application/x-www-form-urlencoded内容类型时，生成z.literal("form-url")
2. 当检测到application/json内容类型时，生成z.literal("json")
3. 其他情况则保持向后兼容

使用示例

以一个典型的OAuth2令牌端点为例，OpenAPI定义如下：

/api/token:
  post:
    requestBody:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/TokenRequest'

现在，typed-openapi生成的类型定义将包含明确的请求格式声明：

export const post_Token = {
  method: z.literal("POST"),
  path: z.literal("/api/token"),
  requestFormat: z.literal("form-url"), // 新增的请求格式声明
  parameters: z.object({
    body: TokenRequest,
  }),
  response: TokenResponse,
};

技术价值

这一改进为开发者带来了多重好处：

1. 更好的开发体验：IDE可以基于类型提示直接显示每个端点所需的请求格式
2. 更强的类型安全：在编译时就能捕获错误的请求格式使用
3. 更清晰的文档：生成的类型定义本身成为API文档的一部分
4. 更好的工具链集成：与其他工具(如API测试工具)的集成更加顺畅

实现原理

在底层实现上，该功能通过解析OpenAPI规范中的content-type信息，将其映射为内部定义的请求格式枚举。核心逻辑包括：

1. 内容类型检测：分析requestBody.content下的媒体类型
2. 格式映射：将OpenAPI媒体类型映射为简化的请求格式标识
3. 类型生成：使用zod的literal类型确保类型精确性

这一改进使得typed-openapi在功能完整性上更进一步，为构建类型安全的API客户端提供了更全面的支持。

typed-openapi Generate a headless Typescript API client from an OpenAPI spec 项目地址: https://gitcode.com/gh_mirrors/ty/typed-openapi