How to provide example value to a Response Body of content-type: text/html in Swagger (to test with dredd)

swagger swagger-ui swagger-2.0 apiary.io apiary

11,461

Solution 1

Figured it out. the response object has a field called "examples" which allows to show examples to your API response.

The syntax is clearly shown in the specification and basically says you need to identify the MIME-type for the example response, in my case text/html and the value is the actual text.

so like this:

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

That's it. Now whether or not dredd knows to take this value and compare it is another story. their docs state that any response other than JSON is validated as plain text so this should work.

Hope this helped.

Solution 2

In case someone needs this in the openapi version 3.0 you can do it this way:

Save your HTML. For example give this at the end of your file:

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

Then you can reference this scheme in responses wherever you want. For example:

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

11,461

Author by

Shachar R

Updated on June 14, 2022

Comments

Shachar R almost 2 years
I have an API call which responds 200 OK and returns an HTML. I would like to add this to my API documentation (especially since i validate it using dredd and unless i provide it with the expected response body the test fails). How would i do this in Swagger?

--- More details --- My Response to an API call is 200 OK and with a one line Response Body:

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

I can easily define the Response Body in Blueprint in the following form:
```
 + 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>`
```
But i'm not sure how to do this in Swagger. Almost all examples i can find are for application/json responses (understandably) and i'm having trouble guessing the correct syntax for this kind of response.

The relevant swagger text in my document is this (so far without specifying the response body, so with an empty body dredd fails because the response body should be <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
```
Please comment if you have any suggestions on this. Thanks!