Open sorenrife opened 2 years ago
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.
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
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.
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 ❤️