8

我有一个 API 调用，它响应 200 OK 并返回一个 HTML。我想将此添加到我的 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 中做到这一点。我能找到的几乎所有示例都是针对应用程序/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

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

4

2 回答 2

12

弄清楚了。响应对象有一个名为“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 之外的任何响应都被验证为纯文本，因此这应该可以工作。

希望这有帮助。

于 2016-08-14T23:02:59.363 回答
1

如果有人在 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'
于 2020-10-02T14:43:55.953 回答