如何在Swagger中为内容类型：text/html的Response Body提供示例值

我有一个响应200 OK并返回HTML的API调用。我想将其添加到我的API文档（特别是因为我使用dredd进行了验证，除非我提供它与期望的响应正文测试失败）。如何我会在Swagger中做到这一点？如何在Swagger中为内容类型：text/html的Response Body提供示例值

---更多细节--- 我通过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: "[email protected]" 
     tags: 
     - Reset Password 
     responses: 
     200: 
      description: Success

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

来源

2016-08-13 Shachar R

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

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

所以这样的：

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

就是这样。现在，不管是否知道采取这个价值并且比较它是另一回事。他们的文档声明除JSON以外的任何响应均以纯文本形式进行验证，因此此应该有效。

希望这有助于。

来源

2016-08-14 23:02:59

如何在Swagger中为内容类型：text/html的Response Body提供示例值

回答

相关问题