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!