Repository navigation
Conversation
/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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.jsonfrom 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:
/api-docs#/message/getMessages,#/plugin/getPluginDisplayand the rest) lands on the operation it names.api-docs/anchors.jsonholds those links.api-docs-fetcher.tsread them.api-docs/fetch-specs.mjsreads 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./api-docs/, so its home page, sitemap and 404 are untouched.What changes:
/api-docs/, so a click doesn't go through a redirect. The sidebar entry reads "API Documentation". Old/api-docslinks still arrive, through GitHub Pages' redirect to/api-docs/./api-docslinks aren't dead (ignoreDeadLinks), since those pages come from the second build step.api-docs.md,api-docs.data.ts,api-docs-fetcher.tsandpublic/swagger/go, since nothing uses them now.yarn buildruns both builds.yarn dev:api-docsruns 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