search

sanic-org / sanic-openapi

Easily document your Sanic API with a UI
https://sanic-openapi.readthedocs.io/
MIT License
505 stars 107 forks source link

deprecate sanic_openapi.api.API #211

Closed artcg closed 3 years ago

artcg commented 3 years ago

This class is quite cumbersome and doesn't seem to add much value to me, beyond that, it is completely undocumented so I would be surprised if anyone beyond it's creator is using it, would therefore recommend to remove it in 0.6.4

For anyone who doesn't know what the class does, it is basically a wrapper around multiple @doc decorators, but to me the boilerplate for the end user of creating a custom subclass of this class, and then the confusion for the end user of what that class would do, takes away the value of reducing the boilerplate of the decorators

artcg commented 3 years ago

Ah there is the Sphinx generated docs for it, so people could have learned about it that way, but either way the warning would recommend people to leave an issue if they would like to keep using it so not a problem there

ahopkins commented 3 years ago

This brings up another question about how to handle versioning and deprecations. I agree 100% that the right approach is to provide the warning with a reference for when that will happen. But, sanic-openapi does not have a regular release cycle.

Maybe it should?

This is probably not the right place for the conversation, but it might make sense to move it to calver similar to the sanic repo. Then it also could copy the same deprecation policy (deprecation notices in 2 releases before removal).

artcg commented 3 years ago

I don't have much opinion about a release schedule, depends how much of a chore it is to do releases like that, but it could be good to integrate with sanic just for making compatibility easier

ahopkins commented 3 years ago

Generally it is fairly simple. The "hardest" task is maintaining a decent changelog. Let's get the next version out, and then maybe jump to calver 21.6. Maybe we decide to just two main releases (X.6 and X.12) per year, and everything in the middle is a patch version.