Skip to content

Build the API docs with sourcey - #109

Open
auscaster wants to merge 1 commit into
gotify:masterfrom
auscaster:docs/sourcey
Open

auscaster wants to merge 1 commit into
gotify:masterfrom
auscaster:docs/sourcey

Conversation

@auscaster

Copy link
Copy Markdown

I wrote to you about this on 9 November. Here it is as a pull request, ready to merge.

This builds /api-docs with sourcey when the site builds, rather than in each reader's browser. It's the same docs/spec.json from the same gotify/server releases, the newest first and every other release in a version picker. The page is complete the moment it loads, so search engines and assistants read the API as readers do, and every operation is also published as Markdown with an llms.txt. Each operation keeps a Try it console.

On the same machine, /api-docs downloads 130 KB in 6 requests instead of 621 KB in 16, holds 0.5 MB of memory instead of 18 MB, and shows its content in 0.60 s instead of 2.25 s.

What's kept:

  • Every deep link into the page today (/api-docs#/message/getMessages, #/plugin/getPluginDisplay and the rest) lands on the operation it names. api-docs/anchors.json holds those links.
  • The releases the picker offers: the tags GitHub lists for gotify/server, as api-docs-fetcher.ts read them. api-docs/fetch-specs.mjs reads the same list before the API docs build, and the workflow passes it the token so the GitHub API doesn't rate-limit the build.
  • The logo, the favicon and the site's blue.
  • The VitePress site itself. The API docs build into its output at /api-docs/, so its home page, sitemap and 404 are untouched.

What changes:

  • The docs' links to the API docs, and the two nav entries, now point at /api-docs/, so a click doesn't go through a redirect. The sidebar entry reads "API Documentation". Old /api-docs links still arrive, through GitHub Pages' redirect to /api-docs/.
  • VitePress is told that /api-docs links aren't dead (ignoreDeadLinks), since those pages come from the second build step.
  • api-docs.md, api-docs.data.ts, api-docs-fetcher.ts and public/swagger/ go, since nothing uses them now.
  • yarn build runs both builds. yarn dev:api-docs runs the API docs locally, as the README now says.

One thing I noticed: the spec.json in v3.1.1 still calls itself version 2.1.0, and v2.9.1's says 2.0.2. So the version under the title doesn't match the release a reader picked. That's in gotify/server's docs/spec.json, not here.

Kam / maintainer, sourcey

/api-docs becomes a static reference of the gotify/server REST API, built
from the docs/spec.json of each release, the newest first and every other
release in the version picker. Every deep link into the previous page
(#/message/getMessages and the rest) lands on the operation it names.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant