Local Headless API Docs

[pennersr]

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.

[pennersr]

Thanks for the positive note! I've turned this into a feature request, over at #3830

[leadrobot]

Awesome. Thanks very much!

[matmair]

Hi there @pennersr!
Do you have a rough idea how this would work / should be implemented?
We are using drf-spectacular at InvenTree. That works pretty well and generates OpenAPI spec files that are well usable for redoc docs (we also auto-generate them and archive them for client-generation purposes https://github.com/inventree/schema/blob/main/export/208/api.yaml).

While I can not commit to a timeline I would be interested if you would want this to be worked on by the community.
My plan would be to add the docs from the spec-file you are providing right now to the API endpoints and use the tools drf-spectacular provides to ensure they fully match.

[pennersr]

@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 SOCIALACCOUNT_ONLY, or the /_allauth/ prefix at which headless is mounted, or a custom signup form, or whether or not MFA is enabled...all impact the API. Once you start dynamically rendering the docs at runtime via an endpoint, that does set expectations that what is rendered is actually matching the live configuration.

All in all, tackling this issue is not that clear cut...

[matmair]

From a user (developer) perspective it would be good if the schema would represent the actual exposed/activated functionality - so iterating over the allauth.urls urlpatterns would be preferable in this way.

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 allauth.headless.base.views.APIView and decorators could work.
What is your general position on the concept of using class/function docstrings and decorators to keep API endpoint docs and the actual code close to each other? Is this an approach you would support?

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.

[pennersr]

What is your general position on the concept of using class/function docstrings and decorators to keep API endpoint docs and the actual code close to each other? Is this an approach you would support?

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:

• A pluggable user model, e.g. the pk field can vary from int to UUID, which reflects on the API.
• Forms, such as a custom signup form with additional fields, affecting the signup payload.

We generate the schema with each push event to GitHub and compare against a known-good to create a status check

That is indeed a different model. For allauth, a simple settings.ACCOUNT_... value can already influence the API.

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 {% if %} statements. Most definitely, this is far from elegant, and does not derive the docs from the models, but it would get the job done.

Just thinking out loud here...

[leadrobot]

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.

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.