clarification that multiple examples per status code and mediatype are supported in OpenApi 3, but not in OpenApi 2
@@ -102,6 +102,12 @@ given to the `document()` method, it must start with the id of the inbound endpo
```
This allows Springfox to collect all spring-restdocs snippets which belong to a particular endpoint.
+Note that the OpenApi 2.0 Specification allows only [one example per response code and media-type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject).
+Starting from OpenApi 3.0 this will [change](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#media-type-object), but Springfox does not support that version yet.
+Therefore, if you have more than one test with a response having the same status code and media-type, Springfox's
+internal data structure does maintain all examples correctly, but the Swagger2 dccumentation will only
+use the first example.
+
Spring-Restdocs records request and response snippets during test execution, by default to the
folder _target/generated-snippets_.
