Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Strawman API Docs #1419

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

bollwyvl
Copy link
Contributor

@bollwyvl bollwyvl commented May 3, 2024

references

code changes

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 image
build-a-GET image
GOT image
400% image

🔔 @Zsailer @tonyfast

@bollwyvl
Copy link
Contributor Author

bollwyvl commented May 3, 2024

@meeseeksdev tag enhancement

Copy link

lumberbot-app bot commented May 3, 2024

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

@bollwyvl
Copy link
Contributor Author

bollwyvl commented May 3, 2024

@blink1073 add the enhancement label 1 minute ago

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

@bollwyvl
Copy link
Contributor Author

bollwyvl commented May 3, 2024

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 bollwyvl marked this pull request as ready for review May 3, 2024 13:45
@bollwyvl
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants