diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index db948b2..78ff5ba 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -15,6 +15,9 @@ jobs: - run: yarn install --frozen-lockfile - run: yarn format:test - run: yarn build + env: + # Lifts GitHub's rate limit for the API docs, which list gotify/server's releases. + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - uses: actions/configure-pages@v5 if: github.event_name == 'push' && github.ref == 'refs/heads/master' - uses: actions/upload-pages-artifact@v3 diff --git a/.gitignore b/.gitignore index c2edd9b..1754f65 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ node_modules .idea .vitepress/cache .vitepress/dist + +# The specs the API docs build downloads +api-docs/specs diff --git a/.vitepress/config.ts b/.vitepress/config.ts index d56214b..be2d488 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -9,6 +9,8 @@ export default defineConfig({ cleanUrls: true, lastUpdated: true, srcExclude: ['README.md'], + // The API docs are built beside the site (yarn build:api-docs), so links to them aren't dead. + ignoreDeadLinks: [/^\/api-docs/], head: [['link', {rel: 'icon', type: 'image/png', href: '/img/favicon.png'}]], @@ -18,7 +20,7 @@ export default defineConfig({ search: {provider: 'local'}, nav: [ {text: 'Docs', link: '/docs/'}, - {text: 'API-Docs', link: '/api-docs'}, + {text: 'API-Docs', link: '/api-docs/'}, ], sidebar: { '/docs/': [ @@ -36,7 +38,7 @@ export default defineConfig({ }, { text: 'REST-API', - items: [{text: 'Swagger Documentation', link: '/api-docs'}], + items: [{text: 'API Documentation', link: '/api-docs/'}], }, { text: 'Plugins', diff --git a/README.md b/README.md index f30e8be..6c817bf 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,10 @@ $ yarn install $ yarn dev ``` + +The API docs at /api-docs are built with [sourcey](https://github.com/sourcey/sourcey) from the +`docs/spec.json` of each gotify/server release (`api-docs/`). To run them locally: + +```bash +$ yarn dev:api-docs +``` diff --git a/api-docs-fetcher.ts b/api-docs-fetcher.ts deleted file mode 100644 index 8779ce6..0000000 --- a/api-docs-fetcher.ts +++ /dev/null @@ -1,13 +0,0 @@ -export const fetchUrls = async () => { - const res = await fetch('https://api.github.com/repos/gotify/server/tags', { - headers: {Accept: 'application/vnd.github.v3+json'}, - }); - if (!res.ok) { - throw Error('could not fetch tags'); - } - const tags: {name: string}[] = await res.json(); - return tags.map((tag) => ({ - url: `https://raw.githubusercontent.com/gotify/server/${tag.name}/docs/spec.json`, - name: tag.name, - })); -}; diff --git a/api-docs.data.ts b/api-docs.data.ts deleted file mode 100644 index 3b73d5f..0000000 --- a/api-docs.data.ts +++ /dev/null @@ -1,8 +0,0 @@ -import {fetchUrls} from './api-docs-fetcher'; - -// This is evaluated at build-time: https://vitepress.dev/guide/data-loading -export default { - async load() { - return fetchUrls(); - }, -}; diff --git a/api-docs.md b/api-docs.md deleted file mode 100644 index 60ef74c..0000000 --- a/api-docs.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: page -title: API Documentation -head: - - [link, {rel: stylesheet, href: /swagger/swagger-ui.css}] - - [script, {src: /swagger/swagger-ui-bundle.js}] - - [script, {src: /swagger/swagger-ui-standalone-preset.js}] ---- - -
- - diff --git a/api-docs/anchors.json b/api-docs/anchors.json new file mode 100644 index 0000000..c6fe105 --- /dev/null +++ b/api-docs/anchors.json @@ -0,0 +1,104 @@ +{ + "introduction": { + "operations-tag-application": "tag-application", + "/application": "tag-application", + "operations-application-getApps": "operation-application-get", + "/application/getApps": "operation-application-get", + "operations-application-createApp": "operation-application-post", + "/application/createApp": "operation-application-post", + "operations-application-updateApplication": "operation-application-id-put", + "/application/updateApplication": "operation-application-id-put", + "operations-application-deleteApp": "operation-application-id-delete", + "/application/deleteApp": "operation-application-id-delete", + "operations-application-uploadAppImage": "operation-application-id-image-post", + "/application/uploadAppImage": "operation-application-id-image-post", + "operations-application-removeAppImage": "operation-application-id-image-delete", + "/application/removeAppImage": "operation-application-id-image-delete", + "operations-application-updateAppSecurity": "operation-application-id-security-put", + "/application/updateAppSecurity": "operation-application-id-security-put", + "operations-tag-message": "tag-message", + "/message": "tag-message", + "operations-message-getAppMessages": "operation-application-id-message-get", + "/message/getAppMessages": "operation-application-id-message-get", + "operations-message-deleteAppMessages": "operation-application-id-message-delete", + "/message/deleteAppMessages": "operation-application-id-message-delete", + "operations-message-getMessages": "operation-message-get", + "/message/getMessages": "operation-message-get", + "operations-message-createMessage": "operation-message-post", + "/message/createMessage": "operation-message-post", + "operations-message-deleteMessages": "operation-message-delete", + "/message/deleteMessages": "operation-message-delete", + "operations-message-deleteMessage": "operation-message-id-delete", + "/message/deleteMessage": "operation-message-id-delete", + "operations-message-streamMessages": "operation-stream-get", + "/message/streamMessages": "operation-stream-get", + "operations-tag-auth": "tag-auth", + "/auth": "tag-auth", + "operations-auth-localLogin": "operation-auth-local-login-post", + "/auth/localLogin": "operation-auth-local-login-post", + "operations-auth-logout": "operation-auth-logout-post", + "/auth/logout": "operation-auth-logout-post", + "operations-tag-oidc": "tag-oidc", + "/oidc": "tag-oidc", + "operations-oidc-oidcCallback": "operation-auth-oidc-callback-get", + "/oidc/oidcCallback": "operation-auth-oidc-callback-get", + "operations-oidc-oidcElevate": "operation-auth-oidc-elevate-get", + "/oidc/oidcElevate": "operation-auth-oidc-elevate-get", + "operations-oidc-externalAuthorize": "operation-auth-oidc-external-authorize-post", + "/oidc/externalAuthorize": "operation-auth-oidc-external-authorize-post", + "operations-oidc-externalToken": "operation-auth-oidc-external-token-post", + "/oidc/externalToken": "operation-auth-oidc-external-token-post", + "operations-oidc-oidcLogin": "operation-auth-oidc-login-get", + "/oidc/oidcLogin": "operation-auth-oidc-login-get", + "operations-tag-client": "tag-client", + "/client": "tag-client", + "operations-client-getClients": "operation-client-get", + "/client/getClients": "operation-client-get", + "operations-client-createClient": "operation-client-post", + "/client/createClient": "operation-client-post", + "operations-client-updateClient": "operation-client-id-put", + "/client/updateClient": "operation-client-id-put", + "operations-client-deleteClient": "operation-client-id-delete", + "/client/deleteClient": "operation-client-id-delete", + "operations-client-elevateClient": "operation-client-id-elevate-post", + "/client/elevateClient": "operation-client-id-elevate-post", + "operations-tag-user": "tag-user", + "/user": "tag-user", + "operations-user-currentUser": "operation-current-user-get", + "/user/currentUser": "operation-current-user-get", + "operations-user-updateCurrentUser": "operation-current-user-password-post", + "/user/updateCurrentUser": "operation-current-user-password-post", + "operations-user-getUsers": "operation-user-get", + "/user/getUsers": "operation-user-get", + "operations-user-createUser": "operation-user-post", + "/user/createUser": "operation-user-post", + "operations-user-getUser": "operation-user-id-get", + "/user/getUser": "operation-user-id-get", + "operations-user-updateUser": "operation-user-id-post", + "/user/updateUser": "operation-user-id-post", + "operations-user-deleteUser": "operation-user-id-delete", + "/user/deleteUser": "operation-user-id-delete", + "operations-tag-info": "tag-info", + "/info": "tag-info", + "operations-info-getInfo": "operation-gotifyinfo-get", + "/info/getInfo": "operation-gotifyinfo-get", + "operations-info-getHealth": "operation-health-get", + "/info/getHealth": "operation-health-get", + "operations-info-getVersion": "operation-version-get", + "/info/getVersion": "operation-version-get", + "operations-tag-plugin": "tag-plugin", + "/plugin": "tag-plugin", + "operations-plugin-getPlugins": "operation-plugin-get", + "/plugin/getPlugins": "operation-plugin-get", + "operations-plugin-getPluginConfig": "operation-plugin-id-config-get", + "/plugin/getPluginConfig": "operation-plugin-id-config-get", + "operations-plugin-updatePluginConfig": "operation-plugin-id-config-post", + "/plugin/updatePluginConfig": "operation-plugin-id-config-post", + "operations-plugin-disablePlugin": "operation-plugin-id-disable-post", + "/plugin/disablePlugin": "operation-plugin-id-disable-post", + "operations-plugin-getPluginDisplay": "operation-plugin-id-display-get", + "/plugin/getPluginDisplay": "operation-plugin-id-display-get", + "operations-plugin-enablePlugin": "operation-plugin-id-enable-post", + "/plugin/enablePlugin": "operation-plugin-id-enable-post" + } +} diff --git a/api-docs/fetch-specs.mjs b/api-docs/fetch-specs.mjs new file mode 100644 index 0000000..3676322 --- /dev/null +++ b/api-docs/fetch-specs.mjs @@ -0,0 +1,22 @@ +// Downloads the REST API document of each gotify/server release the API docs offer, into +// api-docs/specs: the tags GitHub lists for gotify/server, newest first, each tag's +// docs/spec.json, and releases.json naming them in that order. The build runs it first. +import { mkdir, writeFile } from "node:fs/promises"; + +const specs = new URL("./specs/", import.meta.url); +const headers = { Accept: "application/vnd.github.v3+json" }; +// In the workflow the token lifts GitHub's rate limit; a local build works without one. +if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`; + +const res = await fetch("https://api.github.com/repos/gotify/server/tags", { headers }); +if (!res.ok) throw new Error(`Could not list gotify/server tags: ${res.status}`); +const releases = (await res.json()).map((tag) => tag.name); + +await mkdir(specs, { recursive: true }); +await Promise.all(releases.map(async (release) => { + const spec = await fetch(`https://raw.githubusercontent.com/gotify/server/${release}/docs/spec.json`); + if (!spec.ok) throw new Error(`Could not fetch the spec of ${release}: ${spec.status}`); + await writeFile(new URL(`${release}.json`, specs), await spec.text()); +})); +await writeFile(new URL("releases.json", specs), JSON.stringify(releases, null, 2) + "\n"); +console.log(`API docs: ${releases.length} releases, ${releases[0]} first`); diff --git a/api-docs/sourcey.config.ts b/api-docs/sourcey.config.ts new file mode 100644 index 0000000..cb477f6 --- /dev/null +++ b/api-docs/sourcey.config.ts @@ -0,0 +1,44 @@ +import { defineConfig, openapi, type TabVersionsConfig } from "sourcey"; +import anchors from "./anchors.json"; +import releases from "./specs/releases.json"; + +// gotify.net/api-docs: the REST API of the newest gotify/server release, and every release before +// it in the version picker, from the specs fetch-specs.mjs downloads. Every deep link into the +// previous page (#/message/getMessages and the rest) lands on the operation it names. +const [latest, ...earlier] = releases; +const spec = (release: string) => openapi(`./specs/${release}.json`); +const versions: TabVersionsConfig = { + default: latest, + items: [ + { id: latest, label: latest, path: "" }, + ...earlier.map((release) => ({ + id: release, + label: release, + path: release, + source: spec(release), + notice: `The REST API of Gotify server ${release}.`, + index: false, + })), + ], +}; + +export default defineConfig({ + name: "Gotify", + siteUrl: "https://gotify.net", + // Served beneath the VitePress site, which keeps its own home page, sitemap and 404. + baseUrl: "/api-docs", + // Beneath a path, each release is a folder of its own: /api-docs/v3.1.0/. + prettyUrls: "slash", + logo: { light: "../public/img/logo.png", mark: true }, + favicon: "../public/img/favicon.png", + theme: { colors: { primary: "#3498db" } }, + navbar: { + links: [ + { type: "link", href: "https://gotify.net/docs/", label: "Docs" }, + { type: "github", href: "https://github.com/gotify" }, + ], + }, + navigation: { + tabs: [{ id: "api", tab: "API Docs", slug: "", source: spec(latest), anchors, versions }], + }, +}); diff --git a/docs/dev-server-and-tests.md b/docs/dev-server-and-tests.md index 8ce977e..0e360da 100644 --- a/docs/dev-server-and-tests.md +++ b/docs/dev-server-and-tests.md @@ -34,7 +34,7 @@ containing `GOTIFY_SERVER_PORT=8080` to change the port. ## Update Swagger spec -The [gotify/server REST-API](/api-docs) is documented via Swagger. The Swagger definition is generated from source code comments +The [gotify/server REST-API](/api-docs/) is documented via Swagger. The Swagger definition is generated from source code comments ([example comment](https://github.com/gotify/server/blob/09c1516a170dfb47d29644db622655b540b94922/api/application.go#L33)). After changing such a comment, run the following command to update the Swagger definition. diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md index af602ff..15e0aa3 100644 --- a/docs/migrate-to-3.md +++ b/docs/migrate-to-3.md @@ -131,7 +131,7 @@ With a non-elevated client token these return `403`: | `GET /user`, `GET`/`POST`/`DELETE /user/{id}` | Manage users (admin) | The `Client` and `CurrentUser` models now include elevation-related fields. See -the [API documentation](/api-docs) for details. +the [API documentation](/api-docs/) for details. ::: tip diff --git a/docs/plugin-write.md b/docs/plugin-write.md index b8aaa99..e46e001 100644 --- a/docs/plugin-write.md +++ b/docs/plugin-write.md @@ -42,7 +42,7 @@ Plugins can dynamically generate information based on the current state. It receives a `location` parameter contains the server's hostname, port and scheme recovered from the original request to the `Displayer` API. Markdown is supported. -The REST API for this exposed at [`/plugin/:id/display`](/api-docs#/plugin/getPluginDisplay). +The REST API for this exposed at [`/plugin/:id/display`](/api-docs/#/plugin/getPluginDisplay). ```go // Plugin is the plugin instance @@ -178,7 +178,7 @@ func (c *Plugin) GetDisplay(location *url.URL) string { [`Configurer`](https://godoc.org/github.com/gotify/plugin-api#Configurer) is used to provide configuration interfaces to the user. Marshaling and Unmarshaling is handled by the gotify main program. -The REST API for this is exposed at [`/plugin/:id/config`](/api-docs#/plugin/getPluginConfig). +The REST API for this is exposed at [`/plugin/:id/config`](/api-docs/#/plugin/getPluginConfig). ```go // Plugin is the plugin instance diff --git a/docs/pushmsg.md b/docs/pushmsg.md index 7d144a1..19ef859 100644 --- a/docs/pushmsg.md +++ b/docs/pushmsg.md @@ -5,7 +5,7 @@ An application can be added via - WebUI: click the `apps` tab in the upper right corner when logged in and add an application - REST API: `curl -u admin:admin https://push.example.de/application -F "name=test" -F "description=tutorial"` - See [API docs](/api-docs) + See [API docs](/api-docs/) To authenticate as an application you need the application token. The token is returned when creating the application. Starting with Gotify 3, tokens are only shown once, on creation or rotation. diff --git a/package.json b/package.json index 6ca0f73..1d862c1 100644 --- a/package.json +++ b/package.json @@ -4,13 +4,18 @@ "type": "module", "scripts": { "dev": "vitepress dev", - "build": "vitepress build", + "dev:api-docs": "node api-docs/fetch-specs.mjs && sourcey dev -c api-docs", + "build": "vitepress build && yarn build:api-docs", + "build:api-docs": "node api-docs/fetch-specs.mjs && sourcey build -c api-docs -o .vitepress/dist/api-docs", "preview": "vitepress preview", "format": "prettier '**/*.md' '.vitepress/**/*.{ts,css}' --write", "format:test": "prettier '**/*.md' '.vitepress/**/*.{ts,css}' --list-different" }, "dependencies": { - "vitepress": "^1.6.0", - "prettier": "^3.3.3" + "prettier": "^3.3.3", + "vitepress": "^1.6.0" + }, + "devDependencies": { + "sourcey": "^3.9.5" } } diff --git a/public/swagger/SWAGGER-UI-LICENSE b/public/swagger/SWAGGER-UI-LICENSE deleted file mode 100644 index 84505a3..0000000 --- a/public/swagger/SWAGGER-UI-LICENSE +++ /dev/null @@ -1,11 +0,0 @@ -Copyright 2018 SmartBear Software - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. diff --git a/public/swagger/swagger-ui-bundle.js b/public/swagger/swagger-ui-bundle.js deleted file mode 100644 index f2e7ca5..0000000 --- a/public/swagger/swagger-ui-bundle.js +++ /dev/null @@ -1,2 +0,0 @@ -/*! For license information please see swagger-ui-bundle.js.LICENSE.txt */ -!function webpackUniversalModuleDefinition(s,o){"object"==typeof exports&&"object"==typeof module?module.exports=o():"function"==typeof define&&define.amd?define([],o):"object"==typeof exports?exports.SwaggerUIBundle=o():s.SwaggerUIBundle=o()}(this,(()=>(()=>{var s={67526(s,o){"use strict";o.byteLength=function byteLength(s){var o=getLens(s),i=o[0],a=o[1];return 3*(i+a)/4-a},o.toByteArray=function toByteArray(s){var o,i,_=getLens(s),w=_[0],x=_[1],C=new u(function _byteLength(s,o,i){return 3*(o+i)/4-i}(0,w,x)),j=0,L=x>0?w-4:w;for(i=0;i