A while ago, during one of our chat sessions, I talked to @ahopkins regarding the current state of sanic-openapi, and, mostly, why is it somewhat “not attractive” to a lot of developers and how we could proceed to make it something actually usable.
First, the pros about sanic-openapi:
- it’s built for Sanic.
I can’t think of anything else despite that, since even I (@vltr personally speaking about how I love things to be documented and correctly structured) don’t use it in my own projects and even tried to create my own solution, which has a big pitfall (which I’ll put on the cons later).
Now, what I believe it’s the biggest con of sanic-openapi is:
- it introduces another layer (which is only descriptive) of your objects structure and it doesn’t do anything regarding to validation or data-to-object transformation, which leaves the developer to recreate these structures again (using any other library, such as marshmallow, schematics, pydantic, you name it).
I believe this is the big “hold-back” for a lot of people to actually use (and perhaps embrace) the sanic-openapi project. I know it also has some other flaws, but we can work them as well.
My first proposal to get around that, which I linked above, was to use my own ODM library (called middle), which still needs a lot of work to be considered something usable / stable in the future, but it’s in pure Python and very fast (I might dare say it’s even faster than pydantic, but that’s not the discussion to take place in here).
So, in my first proposal, I introduced another problem: not being agnostic with the serialization / ODM library
Now, I believe that what will make sanic-openapi to take a step further into being something really useful is the capability to use the serialization library of your own choosing, being marshmallow, pydantic, attrs, dataclasses, whatever you want - as long as there’s a proper API (into sanic-openapi) where you can “choose” your preferred library and making all the adaptations to correctly handle these 3rd party libraries, either to process them and output their schema into the OpenAPI format or actually process input / output, validating them and writing the end JSON - all of that being highly configurable on a lot of directions (which I have in mind right now).
With the new Sanic router and 21.X versions, I believe this would be an awesome addition to our stack.
For now, I’ll only leave the high-level details I have in mind so I can hear your thoughts. If this goes ahead, we can start thinking on the specifics