如何在 Openapi 3 的运行时更改 header 的名称

Question

我有一个 api，其中 key:value 作为 header 发送到服务器。我想知道我是否可以创建一个动态 header，其名称在运行时间内由客户端填写？我运行 JSON 文件由 swagger-ui 申请。

我的 API 看起来像这样：

curl -x GET $theUrl -h "customKey:customValue"

我希望客户端在运行时间写入与值相同的密钥（即 JSON 文件中 header 的名称）。甚至欢迎 JS 解决方案。

这是 JSON 中的 OpenAPI 3 规范：

"post": {
            "tags": [
                "Object APIs"
            ],
            "summary": "Create or update object metadata",
            "operationId": "CrUp_Object_Metadata",
            "parameters": [
                {
                    "$ref": "#/components/parameters/X-AUTH-Token"
                },
                {
                    "$ref": "#/components/parameters/Account"
                },
                {
                    "$ref": "#/components/parameters/Container"
                },
                {
                    "$ref": "#/components/parameters/Object"
                },
                {
                    "name": "X-Object-Meta-Book",
                    "in": "header",
                    "required": true,
                    "style": "simple",
                    "schema": {
                        "type": "string",
                        "example": "goodbye"
                    }
                }
            ],
            "responses": {
                "202": {
                    "description": "Successful",
                    "headers": {}
                }
            }
        }

如您所见，我有一个“Post”请求。我想将 header "X-Object-Meta-Book" 的名称更改为自定义名称。这样我就可以 post name:value 到服务器了。

图片如下： https://i.stack.imgur.com/VJWML.jpg

Answer 1

OpenAPI 3 本身没有解决这个问题； headers 是名称声明为纯字符串的映射（参见 headers：https://spec.openapis.org/oas/v3.1.0#headerObject）。

这是因为 OpenAPI 的全部意义在于向客户端概述服务器的 well-defined 功能。

要表达您的服务器如何接受和处理 client-defined headers，您可以使用 openapi-extensions 或提供文字说明（您可以在其中使用 markdown 和 emoji）。

在旁注中，HTTP response code 202 does not mean "Successful"，你应该修正它。

如何在 Openapi 3 的运行时更改 header 的名称

how to change name of a header in runtime in Openapi 3

javascript

swagger

swagger-ui

openapi