idea: adding a mega-example for OAS and linking to it, populating almost all examples.

[toumorokoshi]

We have a lot of places today where we are missing OpenAPI examples - this makes the guidance significantly less usable.

Many of these examples overlap with each - for example a best practices get request may also be a good example for using resource types. In addition, updating all of these examples can be very error-prone and toilsome.

It looks like there is this shorthand in the site-generator that provides a way to link to a single example, then only include a sub-section of it. See https://github.com/aep-dev/aep.dev/blob/main/aep/general/0124/aep.md.j2#L25

{% sample 'multiple_many_to_one.oas.yaml', 'Book' %}

The syntax is a little rough (it looks like it does a substring match of some sort, but it's probably sufficient for most examples, and we can refine it to add desired functionality.

Since it's possible to use a single example across multiple, we could just have one mega-example of how an API should look, then just grab snippets from that to populate the various AEP pages. This also comes with the advantage that we only have to maintain one source of truth.

In addition, we now have aepc, which can easily generate AEP-compliant openapi definitions. So we could populate many of the examples by:

1. generating the appropriate example from aepc
2. copying the bookstore example over to aep.dev
3. linking to it everywhere.

If there's examples missing, we can add them to the aepc example, or extend aepc to support that aep pattern.

I think the only blocker here is aep-dev/site-generator#43.

Thoughts?