knuckleswtf / scribe

Generate API documentation for humans from your Laravel codebase.✍
https://scribe.knuckles.wtf/laravel/
MIT License
1.58k stars 280 forks source link

Introduce Adding examples to the OAS3 Media Type Object (Request / Response) #855

Open Dinushasilva opened 1 month ago

Dinushasilva commented 1 month ago

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:

Screenshot 2024-05-18 163231

After:

Scalar:

image

image

Rapidoc

image

image

Stoplight

image

image

Swagger

image

image

I can update the docs, if we can agree on this implementation.

Thank you!

shalvah commented 2 weeks ago

Been busy, will take a look at these sometime this week or next.

shalvah commented 1 week ago

FYI, I've merged https://github.com/knuckleswtf/scribe/pull/792, which I think implements some of this functionality.