Local Headless API Docs about django-allauth HOT 8 OPEN

I think we need to scope this a bit before we can really proceed here.

Must:

• /_allauth/docs endpoint, that renders the documentation.
• Support both Swagger and Redoc through configuration.
• The endpoint can be turned on/off via a setting.
• The documentation dynamically adjusts to the project setup. Particularly:
  • The root URL path is currently "hardcoded" in the documentation.
  • Depending on what apps are enabled, endpoints should be automatically left out. For example, if allauth.usersessions is not installed, its endpoints must not be present in the documentation.
  • Beyond scope: while effort could be spent on having custom signup fields automatically appear in payloads, or non-standard auto fields (e.g. moving from integer pks to string based UUIDs), I think we can leave that out of scope for now.
• It shall still be possible to render a static version of the documentation for Sphinx / docs.allauth.org purposes.

Questions:

• The above would result in documentation that is not integrated with other project specific API docs. Is there anything that can/should/needs-to-be done to accommodate for people wanting to have integrated/unified docs?
• Is it necessary to expose the documentation is JSON format? Note that it is currently YAML based.

from django-allauth.

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

from django-allauth.

Awesome. Thanks very much!

from django-allauth.

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.

from django-allauth.

@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...

from django-allauth.

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.

from django-allauth.

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...

from django-allauth.

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.

from django-allauth.