如何为内容类型的响应正文提供示例值：Swagger 中的 text/html（使用 dredd 进行测试）答案

【问题标题】：How to provide example value to a Response Body of content-type: text/html in Swagger (to test with dredd)如何为内容类型的响应正文提供示例值：Swagger 中的 text/html（使用 dredd 进行测试）
【发布时间】：2016-08-13 14:58:20
【问题描述】：

我有一个响应 200 OK 并返回 HTML 的 API 调用。我想将此添加到我的 API 文档中（特别是因为我使用 dredd 对其进行了验证，除非我向它提供预期的响应主体，否则测试失败）。如何我会在 Swagger 中这样做吗？

--- 更多细节 --- 我对 API 调用的响应为 200 OK，响应正文为一行：

<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>

我可以在蓝图中轻松定义响应体，格式如下：

 + Response 302 (text/html; charset=utf-8)

     + Body

         `<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>`

但我不确定如何在 Swagger 中执行此操作。我能找到的几乎所有示例都是针对 application/json 响应的（可以理解），我遇到了麻烦猜测这种响应的正确语法。

我的文档中相关的招摇文本是这样的（到目前为止没有指定响应正文，所以用一个空的正文dredd 失败，因为响应正文应该是<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>)：

# this is my API spec in YAML
swagger: '2.0'
info:
  title: My API (Swagger)
  description: blablabla
  version: "1.0.0"
# the domain of the service
host: my.domain.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /
produces:
  - application/json; charset=utf-8
paths:
  /users/password:
    post:
      summary: Password Reset
      description: |
        Handles Reset password for existing user.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/html; charset=utf-8
      parameters:
        - name: "user[email]"
          description: email
          in: formData
          required: true
          type: string
          default: "user@gmail.com"
      tags:
        - Reset Password
      responses:
        200:
          description: Success

如果您对此有任何建议，请发表评论。谢谢！

【问题讨论】：

标签： swagger swagger-ui swagger-2.0 apiary.io apiary

【解决方案1】：

想通了。响应对象有一个名为“examples”的字段，允许向您的 API 响应显示示例。

规范中清楚地显示了语法，基本上说您需要识别示例响应的 MIME 类型，在我的例子中是 text/html，值是实际文本。

像这样：

    responses:
      200:
        description: success and returns some html text
        examples:
          text/html: 
            <html><body>Your HTML text</body></html>

就是这样。现在，dredd 是否知道取这个值并比较它是另一回事。他们的文档声明除 JSON 之外的任何响应都被验证为纯文本，所以这应该工作。

希望这会有所帮助。

【讨论】：

【解决方案2】：

如果有人在 openapi 3.0 版中需要这个，你可以这样做：

保存您的 HTML。例如，在文件末尾给出：

components:
  schemas:
    error401:
      type: string
      example: '<html>HTML text</html>'

然后，您可以在任何需要的响应中引用此方案。例如：

  responses:
    '401':
      description: Error
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/error401'

【讨论】：