Add OpenAPI example factories

[sorenrife]

Nowadays, the Sanic OpenAPI extension does not permit to add example requests and responses to your documented views.
I suggest to add a field example to definitions.Response, definitions.RequestBody and definitions.Parameter to support OpenAPI examples.

The class definitions.Components references to OpenAPI examples -I guess-, but is unused. Maybe it's a WIP.

I don't know if it's on the roadmap or actually documented (since I read carefully the documentation and the code and I didn't find any traces of this feature, besides in this class) but it could be a cool feature. The thing that, personally, I miss the most about the OpenAPI standard.

I could open a PR too, if need. I'd be glad to contribute to Sanic Extensions. Just need an approval that what I suggest makes sense!

Thanks ❤️

[ahopkins]

Makes absolute sense, and I would happily welcome a PR. The code base was largely copied from the earlier sanic-openapi package, which had very limited type hinting support. Because of that, there are a lot of fields that are implicit and not easily discovered. This is something that needs to be resolved in the long run. In the short run, I think that it exposed a problem that example is not one of them as you indicated.

[sorenrife]

Cool! I was thinking that since auto-generated examples could lead to unrealistic examples, it could be useful to have a FactoryBoy-ready type approach, where example accepts an instance of RequestBody.body, Response.content etc

So you could have

@openapi.definition(
    summary="Create a new MusicID",
    description="Create a new **MusicID** via a deserialized MusicID",
    body=RequestBody(serializers.MusicIDRequest, example=MusicIDRequestFactory.build()),
    response=[
        oa.Response(Error, status=429, description="too many requests"),
        oa.Response(Error, status=400, description="bad request"),
        oa.Response(Error, status=401, description="user not authenticated"),
        oa.Response(serializers.MusicIDResponse, example=serializers.MusicIDResponseFactory.build()),
    ],
)

And the example fields would be realistic since we'd permit the usage of Faker, FuzzyAttributes...
So is up to the User to match the criteria of the field

class MusicIDRequestFactory(factory.Factory):
    """
    MusicIDRequest factory
    """

    name: str = factory.Sequence(lambda n: "Section configuration %s" % n)
    identifier: str = faker.Faker('uuid')
    creation_title: str = factory.Sequence(lambda n: "Create your Section %s!" % n)
    source: str = fuzzy.FuzzyChoice(SectionConfig.Source, getter=lambda x: x[0])
    optional: bool = False
    max_items: int = fuzzy.FuzzyInteger(1, 10)

    class Meta:
        model = MusicIDRequestFactory

I'd love to hear your thoughts about it

[ahopkins]

Ooo! That's a nice touch. I'm on board with this. Let me know if you want to spec it out with me, or if you want to just throw together a proposal first.