feat: refactoring package

[astagi]

This is an initial idea of refactoring. I moved all the openapi2 related things inside sanic_openapi/openapi2 folder (api.py, spec.py and doc.py included) and renamed sanic_openapi/oas3 folder to sanic_openapi/openapi3.

Now you can use

from sanic_openapi import openapi3_blueprint, openapi

for oas3, and

from sanic_openapi import openapi2_blueprint, doc

for oas2.

Backward compatibility is guaranteed, you can still use

from sanic_openapi import swagger_blueprint

@artcg @ahopkins thoughts? I'll add some minimal documentation later when we take a decision about the new design.

[artcg]

Looks good to me I am happy with that naming and would be good to merge as is, will wait in case ahopkins has some comments ...

[astagi]

Thanks for having merged this PR @artcg I think that it's time to update examples, README and documentation on readthedocs warning users that this oas3 support is experimental and may change in future.. WDYT?

[artcg]

Sure, it would be great if you are happy to do it :) I don't really know how readthedocs works, think @ahopkins would have to collaborate with you on it for the permissions to push to there

[ahopkins]

It will build automatically when we release a version.

[ahopkins]

Sorry, I was focused on a presentation I was giving at a conference this week. I'll respond to a lot of the outstanding items between today and tomorrow.

[astagi]

No problem @ahopkins @artcg I'll give you some documentation asap before the next release! @artcg when you'll review my PR you can check docs changes building files inside /docs folder using Sphinx.

[vltr]

@astagi @artcg I started a topic on the community forums about the future of sanic-openapi and I would love to hear your thoughts :wink:

[artcg]

Cool post @vltr! & your library ‘middle’ seems nice!

I definitely agree with some of your criticisms of sanic openapi, as well as your ideas about future plans. With the scale of the proposed changes though I think it would be necessary (easiest, at least) to start the whole project from scratch and forget about back-compatibility or anything like that, which would be awesome if someone had the time to do it, but it would probably take at least weeks of work

for me, what attracted me to sanic openapi is that I could just stick a blueprint on to my sanic api and without modifying anything, users have an interactive documentation that automatically updates itself as the api changes, then i thought it would be even more cool if users could see my docstrings too so I made some changes to add that...

Overall the changes you suggest are exciting and I would be really interested to follow that progress in any case

[vltr]

Thank you, @artcg !

your library ‘middle’ seems nice!

Thanks, I know it lacks A LOT of features but for now it does well what's needed from it, let's see what can be done in the future :wink:

With the scale of the proposed changes though I think it would be necessary (easiest, at least) to start the whole project from scratch and forget about back-compatibility or anything like that, which would be awesome if someone had the time to do it, but it would probably take at least weeks of work

Yes, that's the idea, since I'm looking forward some features that might get into Sanic in future versions that would be awesome to have any way of documenting on the API, so, yeah, big refactory is out of plans, completely rewrite is more like the way to go.

for me, what attracted me to sanic openapi is that I could just stick a blueprint on to my sanic api and without modifying anything

That's something I have in mind to not break compatibility, let's say, make it a different version and/or adopt Sanic's release schedule, so it would be easier for developers to stick with the old version (of sanic-openapi) just in case they don't want (or can't or need) to migrate to the "overhauled" version.

then i thought it would be even more cool if users could see my docstrings too so I made some changes to add that...

Yup! Now imagine the ability to have the entire OAS3 covered by this new package, not to mention the extra goodies intended :sunglasses:

Overall the changes you suggest are exciting and I would be really interested to follow that progress in any case

That would be really appreciated! Thank you!

[astagi]

@vltr great post! I agree with your criticism about the current package and with @artcg observations and yes, the easiest way is to start from scratch and completely rewrite the package. I'll give middle module a try this afternoon, it looks cool! BTW count on my help in this process!

@artcg what are your thoughts about the near future of the current sanic-openapi module? I mean the new incoming release, new stuff about OAS3 in the official doc, components support.. I think we should keep this module alive and updated, finishing the remaining tasks and then (or in parallel) start thinking about the new module rewrite! I don't know if there are other people waiting for OAS3 support. As you know I discovered Sanic and its OpenAPI package recently, working for Italian department on the Immuni app against the Covid19 emergency: our microservices are based on Sanic and we'd really like to port documentation to OpenAPI 3!

[artcg]

Yeah it is ready to release as far as I am concerned :) can always do a bugfix release if something comes up...

its awesome that you have such a great cause that you are using it for, keeps me motivated to keep it maintained a bit

I dont know if your group would need the securityschema support, could look it into if so, otherwise would probaby leave it until somebody asks for it

[astagi]

@artcg yep they required the securityschema support as well, for now we can mark endpoints as secured using decorators, if it's not a huge work for you it would be an awesome feature to have! Also I can help with that task during the next week!

[ahopkins]

I'll post my thoughts on this in the coming days (either later today or tomorrow) in the Forums. @astagi and @artcg, if you are not already signed up there, please do that so we can keep the conversation moving in one location.