Add an HTML endpoint for /api with interactive docs

[bollwyvl]

References

• https://discourse.jupyter.org/t/how-jupyterhub-identifies-notebooks-or-files-from-url/25471/5

Problem

Finding the docs for the REST API is semi-annoying, and then not particularly interactive.

Proposed Solution

If a user visits e.g. http://127.0.0.1:8888/api in a browser, show them an interactive HTML application (that we don't have to write).

Additional context

This could be achieved by sniffing the accept header on /api in .

The static assets could be provisioned via (likely) some additional npm packages and a small jinja template to inject client settings (e.g. _xsrf).

We ship the OpenAPI Specification for the Jupyter Server REST API. There are a number of static HTML apps that consume OpenAPI specs, and present the spec as human-centric UI, and can also make live requests via JS. Some examples:

• https://github.com/Redocly/redoc
• https://github.com/swagger-api/swagger-ui

This could be demonstrated initially with an extension.

A longer term play would be to build this type of content with the modern Jupyter Client framework, such that it would inherit local theme options.

[manics]

We recently switched to redoc for the JupyterHub API on readthedocs: https://jupyterhub.readthedocs.io/en/latest/reference/rest-api.html
I think it looks quite nice! It works in the way you say- the HTML code is pretty minimal, it's javascript that fetches the openapi spec https://jupyterhub.readthedocs.io/en/latest/_static/rest-api.yml and renders it.

[bollwyvl]

Sure, can take a look at redoc first. They kinda push the veal with their premium product, but if it does the job, and the open source variant isn't too crippled...

[bollwyvl]

#1419 is ready for review: a lot of author doubt in there, and open to ways forward, with a personal bias toward first-party extension and jupyter_server[apidocs] shout-out from this repo (and placeholder content).