Introduce Adding examples to the OAS3 Media Type Object (Request / Response) #855
Conversation
| @@ -248,6 +248,9 @@ | |||
| Strategies\ResponseFields\GetFromResponseFieldAttribute::class, | |||
| Strategies\ResponseFields\GetFromResponseFieldTag::class, | |||
| ], | |||
| 'examples' => [ | |||
| Strategies\Examples\UseExampleTag::class, | |||
There was a problem hiding this comment.
Nice. I feel like attributes are a more convenient way to specify multiple examples, so let's add support for that too.
There was a problem hiding this comment.
@shalvah let me know how you would like me to update the docs, should it be a new section under Eg: Documenting your API
There was a problem hiding this comment.
I'd say you can probably add it under the existing docs for requests and responses.
|
Been busy, will take a look at these sometime this week or next. |
There was a problem hiding this comment.
Thanks for your contribution! This is a nice idea, and thanks for the screenshots. But my concern: How does this fit with the other response methods, especially when you throw in the scenario feature? For instance, the response examples in your test cases are essentially the same as writing @response 200 <...>.
When I think about it, the existing @response- family of tags and annotations are already for specifying example responses, it's pretty much identical to these.
My current view:
- Rather than a generic
@exampletag, let's use the@responsetag and add a@requesttag, to align with the@responsetag. - Let's rather ensure the multiple example requests/responses are correctly written in the OpenAPI spec (I think that's what Allow multiple content types and schemas (via oneOf) according to OpenAPI 3.0 spec #792 is about).
| - 'Group A' | ||
| security: [] | ||
| '/api/withExampleTagTypeRequest': | ||
| get: |
There was a problem hiding this comment.
Hmmm, doesn't seem like the contents match what should be generated here. I don't see any example requests.
|
FYI, I've merged #792, which I think implements some of this functionality. |
This PR introduces to create an entire request or response examples by leveraging existing OAS3 capabilities by allowing multiple examples with arbitrary names.
Having multiple examples will increase user experience as it allows consumers to see different ways that an API can be consumed / requested.
This is by default supported in most documentation tooling to help users pick which example they'd like to see. We could also expand examples into Objects and Parameters at a later stage.
Before:
After:
Scalar:
Rapidoc
Stoplight
Swagger
I can update the docs, if we can agree on this implementation.
Thank you!