如何为内容类型的响应正文提供示例值：Swagger 中的 text/html（使用 dredd 进行测试）
Posted
技术标签:
【中文标题】如何为内容类型的响应正文提供示例值：Swagger 中的 text/html（使用 dredd 进行测试）【英文标题】：How to provide example value to a Response Body of content-type: text/html in Swagger (to test with 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
如果您对此有任何建议，请发表评论。谢谢！
【问题讨论】：
【参考方案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'
【讨论】：
以上是关于如何为内容类型的响应正文提供示例值：Swagger 中的 text/html（使用 dredd 进行测试）的主要内容，如果未能解决你的问题，请参考以下文章
如何为 ios 本地通知内容提供自定义辅助功能文本 - UNNotificationContent