From 854aa1f783a6115c291e4c1c4f255e378e8954bb Mon Sep 17 00:00:00 2001 From: gitglubber Date: Tue, 20 Jan 2026 10:11:14 -0800 Subject: [PATCH] Convert from swagger to API docs. Renamed swagger_api/openapi.yaml to api/openapi.yaml and updated references in docs/api.md. Removed swagger add to requirements.txt --- docs/api.md | 21 +- docs/{swagger_api => api}/openapi.yaml | 121 ++--- docs/api/scalar.html | 260 +++++++++++ docs/swagger_api/index.html | 586 ------------------------- requirements.txt | 1 - 5 files changed, 349 insertions(+), 640 deletions(-) rename docs/{swagger_api => api}/openapi.yaml (96%) create mode 100644 docs/api/scalar.html delete mode 100644 docs/swagger_api/index.html diff --git a/docs/api.md b/docs/api.md index eed26caa..8d8f4864 100644 --- a/docs/api.md +++ b/docs/api.md @@ -6,9 +6,9 @@ This page contains the interactive API documentation for ntfy. You can try out t ### Server Selection -The Swagger UI includes a server selector dropdown at the top of the page. By default, it's configured to use the **public ntfy.sh server**. +The API reference includes a server selector dropdown at the top of the page. By default, it's configured to use the **public ntfy.sh server**. -To use your own ntfy instance, edit `docs/swagger_api/openapi.yaml` and add your server URL to the `servers` section: +To use your own ntfy instance, edit `docs/api/openapi.yaml` and add your server URL to the `servers` section: ```yaml servers: @@ -22,10 +22,23 @@ After editing the file, rebuild the docs with `mkdocs build`. ### Authentication -Click the **Authorize** button (lock icon) in Swagger UI to add your access token. Use the format `Bearer ` or `Basic `. +Click the **Authorize** button (lock icon) in the API reference to add your access token. Use the format `Bearer ` or `Basic `. ### Try It Out Click **Try it out** on any endpoint to test it directly. Parameters will be empty by default - enter your own values to test. - +--- + + + +If you are not redirected automatically, [click here to view the API Reference](api/scalar.html). \ No newline at end of file diff --git a/docs/swagger_api/openapi.yaml b/docs/api/openapi.yaml similarity index 96% rename from docs/swagger_api/openapi.yaml rename to docs/api/openapi.yaml index 5dde54a9..141fcc4d 100644 --- a/docs/swagger_api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -34,6 +34,34 @@ info: Requests may be rate-limited based on IP address or user tier. + ## CORS Proxy + + If you are running ntfy locally and accessing this documentation from "localhost" and attempting to make requests to a hosted ntfy server (like ntfy.sh) you may need to enable the "CORS Proxy" checkbox in the top right corner of the page. + This will proxy the requests through the Scalar server to the hosted ntfy server. **BE Aware** this will count against the rate limit of the Scalar Proxy Server. So you may recieve 429 responses from the remote ntfy server.. + + ## Experimental Endpoints + + The following endpoints are experimental and may be changed or removed in the future. Use at your own risk. + + - Account Management Endpoints + + - Admin Endpoints + + ## Add your own ntfy server + + To add your own ntfy server to the drop down menu, add the following to the `servers` section of "docs/api/openapi.yaml" (or replace the exsiting server with your own https://myntfyserver.editinyaml.com): + + ```yaml + + servers: + - url: https://your-ntfy-instance.com + + description: Your custom server + + ``` + + Once you have added your own custom server you will need to run `mkdocs build` to rebuild the documentation. + ' version: 2.0.0 contact: @@ -45,21 +73,21 @@ info: servers: - url: https://ntfy.sh description: Public ntfy server -- url: https://MyNtfy.com +- url: https://myntfyserver.editinyaml.com description: My NTFY Server tags: - name: Publish description: Publishing messages to topics - name: Subscribe description: Subscribing to topics and receiving messages -- name: Account - description: User account management -- name: Admin - description: Administrative operations -- name: Matrix - description: Matrix push gateway -- name: WebPush - description: Web Push subscriptions +- name: Account - **EXPERIMENTAL** + description: User account management (EXPERIMENTAL) - THESE ENDPOINTS MAY CHANGE, BE REMOVED, OR ADDED TO IN THE FUTURE. +- name: Admin - **EXPERIMENTAL** + description: Administrative operations (EXPERIMENTAL) - THESE ENDPOINTS MAY CHANGE, BE REMOVED, OR ADDED TO IN THE FUTURE. +- name: Matrix + description: Matrix push gateway +- name: WebPush + description: Web Push subscriptions paths: /{topic}: post: @@ -606,7 +634,7 @@ paths: /v1/health: get: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Health check description: Returns server health status operationId: healthCheck @@ -624,7 +652,7 @@ paths: /v1/stats: get: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Server statistics description: Returns public server statistics operationId: getStats @@ -647,7 +675,7 @@ paths: /v1/tiers: get: tags: - - Account + - Account - **EXPERIMENTAL** summary: List available tiers description: Returns list of available subscription tiers with pricing operationId: getTiers @@ -682,7 +710,7 @@ paths: /v1/users: get: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: List users description: Returns list of all users (admin only) operationId: listUsers @@ -703,7 +731,7 @@ paths: $ref: '#/components/responses/Forbidden' post: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Create user description: Creates a new user (admin only) operationId: createUser @@ -746,7 +774,7 @@ paths: $ref: '#/components/responses/TooManyRequests' put: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Update user description: Updates an existing user (admin only) operationId: updateUser @@ -783,7 +811,7 @@ paths: $ref: '#/components/responses/NotFound' delete: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Delete user description: Deletes a user (admin only) operationId: deleteUser @@ -812,7 +840,7 @@ paths: /v1/users/access: put: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Grant user access to topic description: Grants a user access to a topic or topic pattern (admin only) operationId: grantAccess @@ -851,7 +879,7 @@ paths: $ref: '#/components/responses/TooManyRequests' delete: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Reset user access to topic description: Resets user access to a topic (admin only) operationId: resetAccess @@ -881,7 +909,7 @@ paths: /v1/account: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Create account description: Creates a new user account operationId: createAccount @@ -916,7 +944,7 @@ paths: $ref: '#/components/responses/TooManyRequests' get: tags: - - Account + - Account - **EXPERIMENTAL** summary: Get account info description: Returns information about the authenticated user's account operationId: getAccount @@ -934,7 +962,7 @@ paths: $ref: '#/components/responses/Unauthorized' delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Delete account description: Deletes the authenticated user's account operationId: deleteAccount @@ -963,7 +991,7 @@ paths: /v1/account/password: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Change password description: Changes the authenticated user's password operationId: changePassword @@ -998,7 +1026,7 @@ paths: /v1/account/token: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Create access token description: Creates a new API access token for the authenticated user operationId: createToken @@ -1030,7 +1058,7 @@ paths: $ref: '#/components/responses/TooManyRequests' patch: tags: - - Account + - Account - **EXPERIMENTAL** summary: Update access token description: Updates an existing access token operationId: updateToken @@ -1067,7 +1095,7 @@ paths: $ref: '#/components/responses/NotFound' delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Delete access token description: Deletes an access token operationId: deleteToken @@ -1095,7 +1123,7 @@ paths: /v1/account/settings: patch: tags: - - Account + - Account - **EXPERIMENTAL** summary: Update account settings description: Updates the authenticated user's account settings operationId: updateSettings @@ -1130,7 +1158,7 @@ paths: /v1/account/subscription: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Add topic subscription description: Subscribes to a topic operationId: addSubscription @@ -1159,7 +1187,7 @@ paths: $ref: '#/components/responses/TooManyRequests' patch: tags: - - Account + - Account - **EXPERIMENTAL** summary: Update topic subscription description: Updates a topic subscription operationId: updateSubscription @@ -1188,7 +1216,7 @@ paths: $ref: '#/components/responses/NotFound' delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Delete topic subscription description: Unsubscribes from a topic operationId: deleteSubscription @@ -1216,7 +1244,7 @@ paths: /v1/account/reservation: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Reserve topic description: Reserves a topic for exclusive use operationId: reserveTopic @@ -1255,7 +1283,7 @@ paths: /v1/account/reservation/{topic}: delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Delete topic reservation description: Removes a topic reservation operationId: deleteReservation @@ -1280,7 +1308,7 @@ paths: /v1/account/phone: put: tags: - - Account + - Account - **EXPERIMENTAL** summary: Add phone number description: Adds and verifies a phone number for voice call notifications operationId: addPhoneNumber @@ -1312,7 +1340,7 @@ paths: $ref: '#/components/responses/TooManyRequests' delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Delete phone number description: Removes a phone number operationId: deletePhoneNumber @@ -1341,7 +1369,7 @@ paths: /v1/account/phone/verify: put: tags: - - Account + - Account - **EXPERIMENTAL** summary: Request phone verification code description: Requests a verification code via SMS operationId: verifyPhoneNumber @@ -1376,7 +1404,7 @@ paths: /v1/account/billing/portal: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Create billing portal session description: Creates a Stripe billing portal session operationId: createBillingPortal @@ -1399,7 +1427,7 @@ paths: /v1/account/billing/subscription: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Create subscription description: Creates a paid subscription via Stripe checkout operationId: createSubscription @@ -1434,7 +1462,7 @@ paths: $ref: '#/components/responses/Unauthorized' put: tags: - - Account + - Account - **EXPERIMENTAL** summary: Update subscription description: Modifies an existing subscription operationId: updateSubscription @@ -1461,7 +1489,7 @@ paths: $ref: '#/components/responses/Unauthorized' delete: tags: - - Account + - Account - **EXPERIMENTAL** summary: Cancel subscription description: Cancels the paid subscription operationId: cancelSubscription @@ -1476,7 +1504,7 @@ paths: /v1/account/billing/subscription/success/{CHECKOUT_SESSION_ID}: get: tags: - - Account + - Account - **EXPERIMENTAL** summary: Subscription checkout success description: Handles successful Stripe checkout redirect operationId: subscriptionCheckoutSuccess @@ -1500,7 +1528,7 @@ paths: /v1/account/billing/webhook: post: tags: - - Account + - Account - **EXPERIMENTAL** summary: Stripe webhook handler description: Handles incoming webhooks from Stripe operationId: stripeWebhook @@ -1695,7 +1723,7 @@ paths: /metrics: get: tags: - - Admin + - Admin - **EXPERIMENTAL** summary: Prometheus metrics description: Returns Prometheus-compatible metrics operationId: getMetrics @@ -1806,14 +1834,11 @@ components: schema: type: integer enum: - - 1 - - 2 - 3 + - 2 + - 1 - 4 - 5 - default: - value: 3 - example: 3 min: value: 1 urgent: @@ -1915,7 +1940,6 @@ components: - false - 1 - 0 - default: true XFirebase: name: X-Firebase in: header @@ -1927,7 +1951,6 @@ components: - false - 1 - 0 - default: true XMarkdown: name: X-Markdown in: header @@ -1968,8 +1991,8 @@ components: schema: type: string enum: - - true - false + - true - 1 - 0 - up diff --git a/docs/api/scalar.html b/docs/api/scalar.html new file mode 100644 index 00000000..b44069e4 --- /dev/null +++ b/docs/api/scalar.html @@ -0,0 +1,260 @@ + + + + + + ntfy API Reference + + + + + +
+
+ + ntfy logo + +
+

ntfy

+

API Reference

+
+
+ Documentation Home + ntfy.sh + GitHub +
+ + +
+
+
+
+ +
+ + + + + + + diff --git a/docs/swagger_api/index.html b/docs/swagger_api/index.html deleted file mode 100644 index 6596a288..00000000 --- a/docs/swagger_api/index.html +++ /dev/null @@ -1,586 +0,0 @@ - - - - - - ntfy API Reference - - - - - - -
-
- - ntfy logo - -
-

ntfy

-

API Reference

-
-
- Documentation Home - ntfy.sh - GitHub -
-
-
- - -
-
-
- Server URL: - - -
-
- - Authentication: Click the Authorize button (lock icon) in the top right to add your access token (e.g., tk_your_token_here).
- Try It Out: Click "Try it out" on any endpoint to test it directly in your browser. - -
-
-
- - -
-
-
- - - - - - - diff --git a/requirements.txt b/requirements.txt index 04e81ebd..9c2212a8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ # The documentation uses 'mkdocs', which is written in Python mkdocs-material mkdocs-minify-plugin -mkdocs-swagger-ui-tag