Strawman API Docs

[bollwyvl]

references

• Add an HTML endpoint for /api with interactive docs #1418

code changes

• add swagger-ui-dist to package.json
• add /api/apidocs endpoint

alternatives

• looked at redoc per Add an HTML endpoint for /api with interactive docs #1418 (comment)
  • has hard-coded tracking logo served from third-party site
  • don't feel like hostile-forking it
  • also brought in ~100mb of node_modules
• mounting it on /api (or even api/spec.yaml?docs) would be strictly better, but these both seemed finicky to sniff based on headers, and sometimes be static file or JSON or whatever, and probably not worth the hassle
• could be separately configurable, but if you have the rights to access the spec.yaml

assessment

• this is an important feature
  • but not convinced this belongs in core, given the size
  • however, an officially-supported extension, potentially with a jupyter_server[apidocs] would probably be pretty good

screens

note	screen
basic
build-a-GET
GOT
400%

🔔 @Zsailer @tonyfast

[bollwyvl]

@meeseeksdev tag enhancement

[lumberbot-app]

Awww, sorry bollwyvl you do not seem to be allowed to do that, please ask a repository maintainer.

[bollwyvl]

@blink1073 add the enhancement label 1 minute ago

I knew it! All the bots are just more Steves! ❤️ 🎸

[bollwyvl]

Locally, it looks like the 1.4mb slug of JS doubles the size of the wheel:

383kb jupyter_server-2.14.0-py3-none-any.whl
792kb jupyter_server-2.15.0.dev0-py3-none-any.whl

That's... not actually as bad as I expected for a full, robust, and extremely useful app, but still pretty heavy.

It's possible that size could be further tightened up, but would likely require hundreds of megabytes of node_modules to get a more purposeful build. I didn't even follow redocly down this far, but imagine it's substantially larger on both fronts (and semi-shady).

I'll mark this ready for review, but am still not convinced it should be added to core, and will let others weigh in before going any further. For example:

• there are dozens of knobs to turn
  • these could be hoisted to e.g. page_config or injected directly
• curl is magical and great, but i feel like having jupyter-adjacent code snippets (e.g. python, browser) would be more useful to users

But really... extensions should be able to extend the spec via the existing conf.dmechanism, and reference existing schema parts, and both extensions and core should be able to declaratively hide parts of the docs based on auth resources. And it should all be l10n-aware.

All of this points to complexity that would be better handled in an extension, and even if jupyter_server:

• reserved the expected route showing HTML install instructions for...
• a jupyter_server[apidocs] extra that depended on the new extension

[bollwyvl]

During the jupyter servers and kernels call last week, @vidartf raised the question of exposing additional openapi specs. This points to another potential use case, where an extension (or otherwise wrapped service, e.g. via jupyter-server-proxy) has an existing contract and would like it to be exposed via some mechanism, e.g. dropdown in the /apidocs page:

             :(). jupyter

[Jupyter Server       v]
| Other Extension      |
| Wrapped Appplication |

This could probably be deep linked via some GET param, e.g. /api/apidocs/?spec=/api/app1/swagger.yml.

This doesn't handle the case where an extension overloads an existing route (perhaps by adding some new fields or metadata).

Another thought: currently docs/ is unclaimed. I've very much wanted to see a well-known location on disk (e.g. $PREFIX/share/jupyter/docs which would allow other kinds of documentation to be hosted and, critically, made available via indexed search, and docs/api might be a very nice place indeed to start that process. I'm currently unaware of a broadly-used way to describe "there's some interactive documentation at this relative URL," which seems like an important starting point to making this useful and discoverable.