Apiable的OpenAPI解析器无法正确解析x-www-form-urlencoded请求体

问题背景 #

使用Apiable的API门户测试并发布预开发API时，遇到以下问题：

• 当认证请求的Content-Type为application/x-www-form-urlencoded时，Apiable的文档解析器无法正确展示请求体属性；
• Content-Type为application/json的其他请求可正常解析；
• 该OpenAPI文档在其他平台可正常解析，推测问题源于Apiable自身解析引擎；
• 曾尝试按旧格式修改JSON但无效。

先修正代码中的语法错误 #

你提供的代码片段里，/api/oauth2/token的requestBody部分存在明显JSON语法错误——schema字段多嵌套了一层不必要的大括号，部分容错性高的解析器能忽略，但Apiable引擎可能对语法更敏感，先修正这个问题：

修正后的基础代码 #

"/api/oauth2/token": {
  "post": {
    "tags": ["V1 Endpoints"],
    "summary": "Auth Request",
    "description": "User makes auth request to obtain auth token.",
    "requestBody": {
      "content": {
        "application/x-www-form-urlencoded": {
          "schema": {
            "$ref": "#/components/schemas/AuthClientCredentialsRequest"
          }
        }
      },
      "required": true // 建议添加，明确请求体为必填
    },
    "responses": {
      "200": {
        "$ref": "#/components/responses/AuthResponse"
      },
      "400": {
        "$ref": "#/components/responses/ErrorResponse"
      }
    }
  }
}

替代方案（若语法修正后仍无效） #

方案1：内联定义schema，不使用$ref #

部分解析引擎对application/x-www-form-urlencoded类型的$ref支持不佳，直接将认证请求的schema内联写入：

"/api/oauth2/token": {
  "post": {
    "tags": ["V1 Endpoints"],
    "summary": "Auth Request",
    "description": "User makes auth request to obtain auth token.",
    "requestBody": {
      "content": {
        "application/x-www-form-urlencoded": {
          "schema": {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string",
                "description": "客户端ID"
              },
              "client_secret": {
                "type": "string",
                "description": "客户端密钥"
              },
              "grant_type": {
                "type": "string",
                "enum": ["client_credentials"],
                "description": "授权类型"
              }
            },
            "required": ["client_id", "client_secret", "grant_type"]
          }
        }
      },
      "required": true
    },
    "responses": {
      "200": {
        "$ref": "#/components/responses/AuthResponse"
      },
      "400": {
        "$ref": "#/components/responses/ErrorResponse"
      }
    }
  }
}

方案2：添加application/json兼容类型 #

如果后端支持JSON格式的认证请求，可以同时添加application/json类型的请求体，Apiable能正常解析JSON类型的schema，保证文档展示正常，用户测试时可选择JSON格式：

"requestBody": {
  "content": {
    "application/x-www-form-urlencoded": {
      "schema": {
        "$ref": "#/components/schemas/AuthClientCredentialsRequest"
      }
    },
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthClientCredentialsRequest"
      }
    }
  },
  "required": true
}

内容的提问来源于stack exchange，提问作者user26728383