experimenting for Swagger api docs

[sinisaos]

@dantownsend Small changes for Piccolo admin api. Experimenting for Swagger admin api docs.

[dantownsend]

@sinisaos I had a play around with it locally. You're right about the CSRF thing being a pain.

I was hoping that the Swagger docs would be configurable, and we could tell it to embed the CSRF token in the header of each request, but this doesn't seem possible.

https://swagger.io/docs/specification/authentication/cookie-authentication/

As you mentioned, we could add a CSRF field to each form, but it's not a great user experience, as they would have to copy the CSRF token into that field each time they did a POST.

Even without being able to POST data, it's still useful as documentation though using Redoc.

[sinisaos]

@dantownsend You are absolutely right. I forget about Redoc (which looks much nicer) and with it we get free api documentation with all the methods and parameters per table. For interactivity we have Piccolo admin UI :) which is much better, easier and with much more features than Swagger UI. If you are going to merge this I can make another commit to update Piccolo admin Read the Docs to show users for that possibility and to add title with sitename and description with table name to FastAPI instance in FastAPIWrapper in admin endpoints.py.

[dantownsend]

@sinisaos Yes, feel free to extend the docs. I do intend on merging it in, but will play around with it a bit more at the weekend.

At the moment we have documentation for the /api/tables/<tablename> endpoints, but I'd like to see if the following can also be added too:

/api/tables
/api/meta
/api/user

It's not super important, but would be nice to have it all documented.

[sinisaos]

@dantownsend Can you resolve this conflict or I need to remove FastAPI from requirements.txt and add this to endpoints.py?

try:
    from fastapi import FastAPI
except ImportError:
    print(
        "Install fastapi to use this feature - "
        "pip install piccolo_api[fastapi]."
    )

Thanks.

[dantownsend]

@sinisaos I've resolved the merge conflicts - didn't realise you could do it from within the GitHub GUI.

[sinisaos]

@dantownsend Thanks. Please check for errors in new docs file because I am not a native English speaker.

[dantownsend]

@sinisaos Cool, no problem - I'll merge it into a feature branch and have a play around.

[sinisaos]

@dantownsend Great. Thanks.