Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@ node_modules
.idea
.vitepress/cache
.vitepress/dist

# The specs the API docs build downloads
api-docs/specs
6 changes: 4 additions & 2 deletions .vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'}]],

Expand All @@ -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/': [
Expand All @@ -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',
Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
13 changes: 0 additions & 13 deletions api-docs-fetcher.ts

This file was deleted.

8 changes: 0 additions & 8 deletions api-docs.data.ts

This file was deleted.

34 changes: 0 additions & 34 deletions api-docs.md

This file was deleted.

104 changes: 104 additions & 0 deletions api-docs/anchors.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
22 changes: 22 additions & 0 deletions api-docs/fetch-specs.mjs
Original file line number Diff line number Diff line change
@@ -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`);
44 changes: 44 additions & 0 deletions api-docs/sourcey.config.ts
Original file line number Diff line number Diff line change
@@ -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 }],
},
});
2 changes: 1 addition & 1 deletion docs/dev-server-and-tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/migrate-to-3.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/plugin-write.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/pushmsg.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 8 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
11 changes: 0 additions & 11 deletions public/swagger/SWAGGER-UI-LICENSE

This file was deleted.

2 changes: 0 additions & 2 deletions public/swagger/swagger-ui-bundle.js

This file was deleted.

2 changes: 0 additions & 2 deletions public/swagger/swagger-ui-standalone-preset.js

This file was deleted.

3 changes: 0 additions & 3 deletions public/swagger/swagger-ui.css

This file was deleted.

Loading