Don't build request/response example pairs for all produces types

[kylef]

This changes the behaviour of the request/response example pair generation for Swagger 2.0 so that it will not always use all of the produces content types while generating response examples. The new behaviour is as follows:

• Use ALL examples content types for response generation
• If no examples, use ONLY first JSON content type
• Fallback to empty response

This aims at solving various problems where response pair generation for certain content types is not intended. Here's an example:

produces:
- application/json
- application/problem+json
paths:
  /:
    get:
      responses:
        200:
          schema:
            type: object
        400:
          examples:
            application/problem+json

In this case, I will have two request/response pairs. The first response will be of 200 status code using the first JSON content type which is application/json. Since the second response (400 status code) has an explicit examples section, no produces will be used during response generation and only the explicit content type application/problem+json will be used.

The downside to this is that if I have multiple content types in produces for example application/json and text/json and I'd like to have response pairs for each types this would no longer be generated unless I explicitly added example response bodies for both types.

Dependencies

• [ ] https://github.com/apiaryio/swagger-zoo/pull/51

I'd appreciate if both @honzajavorek could take a look at this PR in consideration of Dredd and the mock server, and @zdne to take a look to see if this works for all his cases.

[honzajavorek]

So the example Swagger document behaves completely the same in following two cases, am I correct?

produces:
- application/json
- application/problem+json

produces:
- application/json

Because any other then the first produces gets ignored unless explicitly specified with the response example.

[kylef]

@honzajavorek Correct

[honzajavorek]

You mention first JSON content type everywhere. Does that mean if the first produces is text/plain, it is skipped until explicitly specified with the response example? How much are non-JSON responses supported now?

[kylef]

@honzajavorek That is correct. There is no behaviour for example generation for non JSON content types in produces. Produces without examples of non-JSON types are ignored. This could be changed in future though, generation of application/x-www-form.. etc for produces would be relatively simple change if desired. We do similar generations for consumes request bodies.

[honzajavorek]

@kylef But this is only about produces/consumes, right? If I put non-JSON type to examples, it will work, no? With JSON recognized, forms recognized, and other things left as provided (text, html?).

[kylef]

@honzajavorek that is also correct. If there are explicit examples they will always be used, regardless of the content-type.

[honzajavorek]

(Also, tests failed but I guess that's because of zoo...)