-
-
Notifications
You must be signed in to change notification settings - Fork 3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Local Headless API Docs #3830
Comments
Thanks for the positive note! I've turned this into a feature request, over at #3830 |
Awesome. Thanks very much! |
Hi there @pennersr! While I can not commit to a timeline I would be interested if you would want this to be worked on by the community. |
@matmair I must admit, I haven't given this much thought, but one thing that is clear is that allauth will not become dependent on external dependencies for this. So "use the tools drf-spectacular provides" is unlikely to fit. Options vary from just distributing the spec as part of allauth (so that it is available when pip installing) and let upstream projects integrate that into their own tooling, or, including some endpoints along the lines of https://github.com/vitalik/django-ninja/tree/master/ninja/openapi inside allauth.headless. There is also challenges though. Currently, the doc is static, yet, project specific configuration can actually impact the API. For example, a setting like All in all, tackling this issue is not that clear cut... |
From a user (developer) perspective it would be good if the schema would represent the actual exposed/activated functionality - so iterating over the drf-spectacular mainly introspects the views in the urlpatterns and combines the results with optional decorators. A lot of edge cases that the libary covers do not apply to allauth. Building something similar based off of introspection of At InvenTree (which has certainly a different thread model and target audience as a system) we provide dynamic schema generation and use this functionality to also ensure that API changes are reflected in docs / version numbers. We generate the schema with each push event to GitHub and compare against a known-good to create a status check. |
In theory, yes, that would be good. Though, I have some reservations as to whether or not the amount of code & effort to get this going is not too high. For example, it would need to deal with various cases:
That is indeed a different model. For allauth, a simple Perhaps to keep things more KISS and not to have to write a complete introspection framework from scratch, it would be feasible to render the OpenAPI YAML file as a template. Then, the few cases where e.g. the user model or signup form affect the API could be implemented by means of some simple context vars passed to the template, and the settings could just be a few Just thinking out loud here... |
For what its worth, this is pretty much the approach I have taken... Loaded the yaml and written an ugly function that iterates through the paths and replaces values where need be (for example headless is at api/auth/ instead of _allauth/ as you mentioned in a previous post). And then I Indeed served the docs using ninja's tools. An endpoint that outputs a "personalized" OpenAPI yaml/json with conditional logic based on allauth settings is plenty if you ask me. Also happy to contribute if I can in any way. |
I think we need to scope this a bit before we can really proceed here. Must:
Questions:
|
Discussed in #3793
Originally posted by leadrobot May 9, 2024
Firstly. Thank you @pennersr and contributors so much for the headless feature. This has been a sorely needed feature not only for the allauth community but the Django community for a long time! Look forward to spending the weekend removing all my hacky, insecure auth code :P
In an effort to create my own unified API docs for the front-end guys, I have downloaded the yaml file from https://docs.allauth.org/en/dev/headless/openapi-specification/ as I couldn't find any mention of it in the source code. Then I added some code to update my API's schema with the allauth schema before serving with Swagger (I'm using Ninja API). This works fine, however I assume the openapi-specification could change in the future and if I updated all-auth my docs would be incorrect.
While I could link to the allauth hosted docs, our devs would miss Swagger's "Try it yourself" functionality and people building public API's would probably prefer to have unified documentation. BTW If I have missed a more obvious way to serve the API docs please let me know otherwise I thought I might suggest:
3rd prize: Include openapi schema in source code.
2nd prize: Provide a utility function that takes an API schema and injects it with the allauth API schema
1st prize: Include autogenerated API docs similar to Ninja or Spectacular with Redoc/Swagger options. Would probably be cleanest to have separate auth and application API docs and link between the two.
The text was updated successfully, but these errors were encountered: