返回HTML内容的API的正确OpenAPI规范编写方法

你现在写的响应部分在OpenAPI 3.x里语法合法、能被工具正常识别，但不算完整的正式定义，具体说明：

• 简易写法的适用场景：如果只是内部快速对接、不需要做严格的接口校验或生成标准化客户端代码，你现在空着text/html下schema的写法完全能用，工具不会报错，也能清晰传递"接口返回HTML页面"的核心信息。
• 正式定义的补全方式：按OpenAPI规范，每个媒体类型的声明都需要明确对应的数据schema，动态生成的HTML本质就是字符串类型的响应内容，不需要定义复杂的结构化约束，只要补全string类型的schema即可，补全后的200响应参考如下：

"responses": {
  "200": {
    "description": "Returns the HTML page for a UI to manage the instance.",
    "content": {
      "text/html; charset=utf-8": {
        "schema": {
          "type": "string",
          "description": "根据传入的instanceCode、identifier路径参数动态生成的HTML页面内容"
        }
      }
    }
  }
}

• 几个实用提示：
  • 建议在媒体类型后追加; charset=utf-8明确字符集，避免部分文档工具、客户端解析返回内容时出现乱码
  • 不用给动态HTML强行加正则匹配、固定结构这类schema约束，这类页面内容是动态生成的，没有固定格式，加这类校验没有实际意义
  • 如果需要更完善的接口定义，可以补充403（无访问权限）、404（对应实例不存在）等错误响应，不补充也不影响200响应HTML部分的定义有效性

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