swagger - 更正用于从 API 调用返回 HTML 的 OpenAPI 规范

Question

我知道这听起来可能很奇怪，但我们有一个 API，我们可以根据传入的有效负载返回生成的 HTML 内容。

我只是想知道这种 api 的 Open API 调用的正式定义是什么，特别是下面的响应部分。

就这么简单吗？

    "paths": {
    "/instance/UI/{instanceCode}/{identifier}": {
        "get": {
            "summary": "Returns the UI which allow the instances answer to be managed by a user",
            "operationId": "instanceUIGet",
            "parameters": [
                {
                    "name": "instanceCode",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "identifier",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ],
            "responses": {
                "200": {
                    "description": "Returns the HTML page for a UI to manage the instance.",
                    "content": {
                        "text/html": {
                        }
                    }
                }
            }
        }
    },

Answer 1

要么是

"responses": {
    "200": {
        "description": "Returns the HTML page for a UI to manage the instance.",
        "content": {
            "text/html": {}    // no schema needed
        }
    }
}

(如您的示例)

或

"responses": {
    "200": {
        "description": "Returns the HTML page for a UI to manage the instance.",
        "content": {
            "text/html": {
                "schema": {
                    "type": "string"
                }
            }
        }
    }
}

Some comments OpenAPI 规范维护者建议 text/* 媒体类型不需要 schema，因为它们的语义完全由媒体类型本身定义。但是，如果您在 specification itself 中搜索 text/ ，您会注意到在一些使用 text/* 媒体类型的示例中使用了 schema。看起来官方对此没有立场(或者规范中的示例可能不太正确)。