multipleof4/ntfy
1
0
Fork 0
mirror of https://github.com/multipleof4/ntfy.git synced 2026-10-09 05:15:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refine open API docs

Browse Source
This commit is contained in:
binwiederhier
2026-01-20 17:13:50 -05:00
parent d2e0588037
commit a06550a90f
6 changed files with 48437 additions and 888 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api.md
-44
View File
@@ -1,44 +0,0 @@
# API Reference
This page contains the interactive API documentation for ntfy. You can try out the API endpoints directly from this page.
## Using the API Documentation
### Server Selection
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/api/openapi.yaml` and add your server URL to the `servers` section:
```yaml
servers:
- url: https://ntfy.sh
description: Public ntfy server
- url: https://your-ntfy-instance.com
description: Your custom server
```
After editing the file, rebuild the docs with `mkdocs build`.
### Authentication
Click the **Authorize** button (lock icon) in the API reference to add your access token. Use the format `Bearer <your_token>` or `Basic <base64_encoded_credentials>`.
### 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.
---
<script>
// Redirect to standalone Scalar page - use absolute path from root
var currentPath = window.location.pathname;
// Get base path (everything before /api/)
var basePath = currentPath.substring(0, currentPath.indexOf('/api/'));
if (basePath === -1 || basePath === '') {
basePath = '';
}
window.location.href = basePath + '/api/scalar.html';
</script>
If you are not redirected automatically, [click here to view the API Reference](api/scalar.html).
docs/api/scalar.html → docs/api/index.html
+32 -100
View File
@@ -4,7 +4,7 @@
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ntfy API Reference</title>
<link rel="icon" type="image/svg+xml" href="https://ntfy.sh/static/img/favicon.svg">
<link rel="icon" type="image/png" href="/static/img/favicon.png">
<style>
* {
margin: 0;
@@ -70,43 +70,22 @@
opacity: 1;
}
/* Proxy toggle checkbox */
.proxy-toggle {
display: flex;
align-items: center;
gap: 8px;
margin-left: 20px;
padding: 8px 12px;
background: rgba(255, 255, 255, 0.15);
border-radius: 6px;
cursor: pointer;
transition: background 0.2s;
}
.proxy-toggle:hover {
background: rgba(255, 255, 255, 0.25);
}
.proxy-toggle input[type="checkbox"] {
cursor: pointer;
width: 16px;
height: 16px;
}
.proxy-toggle label {
color: white;
font-size: 13px;
font-weight: 500;
cursor: pointer;
user-select: none;
}
/* Scalar container */
#scalar-api-reference {
width: 100%;
min-height: calc(100vh - 100px);
}
/* Hide Share and Generate SDKs menu items */
[data-scalar-menu-item="share"],
[data-scalar-menu-item="sdk"],
.scalar-card-header-actions button[title="Share"],
.scalar-card-header-actions button[title="Generate SDK"],
button:has(> span:contains("Share")),
button:has(> span:contains("SDK")) {
display: none !important;
}
/* Responsive */
@media (max-width: 768px) {
.header-content {
@@ -126,7 +105,7 @@
<div class="header">
<div class="header-content">
<a href="/" style="display: flex; align-items: center; text-decoration: none;">
<img src="https://docs.ntfy.sh/static/img/ntfy.png" width="35" height="35" alt="ntfy logo" style="margin-right: 10px;">
<img src="/static/img/ntfy.png" width="35" height="35" alt="ntfy logo" style="margin-right: 10px;">
</a>
<div class="header-text">
<h1>ntfy</h1>
@@ -136,61 +115,16 @@
<a href="/">Documentation Home</a>
<a href="https://ntfy.sh">ntfy.sh</a>
<a href="https://github.com/binwiederhier/ntfy">GitHub</a>
<div class="proxy-toggle" title="Enable CORS proxy to make requests through Scalar's proxy server">
<input type="checkbox" id="proxy-toggle-checkbox" checked>
<label for="proxy-toggle-checkbox">Use CORS Proxy</label>
</div>
</div>
</div>
</div>
<!-- Scalar API Reference -->
<div id="scalar-api-reference"></div>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.43.8/dist/browser/style.css" />
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.43.8/dist/browser/standalone.js"></script>
<link rel="stylesheet" type="text/css" href="./scalar-style.css" />
<script src="./scalar-standalone.js"></script>
<script>
// Store the Scalar instance globally so we can reinitialize it
let scalarInstance = null;
// Get proxy preference from localStorage (default: true)
function getProxyEnabled() {
const stored = localStorage.getItem('scalar-proxy-enabled');
return stored === null ? true : stored === 'true';
}
// Save proxy preference to localStorage
function setProxyEnabled(enabled) {
localStorage.setItem('scalar-proxy-enabled', enabled.toString());
}
// Initialize checkbox state
function initProxyCheckbox() {
const checkbox = document.getElementById('proxy-toggle-checkbox');
if (checkbox) {
checkbox.checked = getProxyEnabled();
// Add change listener
checkbox.addEventListener('change', function() {
const enabled = checkbox.checked;
setProxyEnabled(enabled);
// Reinitialize Scalar with new proxy setting
reinitializeScalar();
});
}
}
// Reinitialize Scalar with current proxy setting
function reinitializeScalar() {
const targetElement = document.getElementById('scalar-api-reference');
if (targetElement) {
// Clear the container
targetElement.innerHTML = '<div style="padding: 20px; text-align: center; color: #6b7280;">Reinitializing API Reference...</div>';
// Reinitialize
setTimeout(initScalar, 100);
}
}
function initScalar() {
const targetElement = document.getElementById('scalar-api-reference');
@@ -204,14 +138,25 @@
return;
}
// Get proxy setting
const useProxy = getProxyEnabled();
// Build config object
const config = {
url: './openapi.yaml',
layout: 'modern',
theme: 'default',
customCss: `
/* Hide Share and Generate SDKs menu items in dropdowns */
[data-testid="share-button"],
[data-testid="sdk-button"],
.context-menu-item:has(svg[data-icon="share"]),
.context-menu-item:has(svg[data-icon="sdk"]),
.dropdown-item:has(span:contains("Share")),
.dropdown-item:has(span:contains("SDK")),
.scalar-dropdown-item[data-action="share"],
.scalar-dropdown-item[data-action="generate-sdk"],
button[aria-label="Share"],
button[aria-label="Generate SDK"] {
display: none !important;
}
`,
configuration: {
hideSidebar: false,
hideSearch: false,
@@ -223,36 +168,23 @@
darkMode: false,
withDefaultFonts: false,
},
};
// Only add proxyUrl if enabled
if (useProxy) {
config.proxyUrl = 'https://proxy.scalar.com';
}
};
try {
const apiRef = Scalar.createApiReference('#scalar-api-reference', config);
console.log('Scalar initialized successfully', useProxy ? 'with proxy' : 'without proxy');
Scalar.createApiReference('#scalar-api-reference', config);
} catch (error) {
console.error('Error initializing Scalar:', error);
targetElement.innerHTML = '<div style="padding: 20px; color: red;">Error loading API reference: ' + error.message + '</div>';
}
}
// Initialize checkbox first
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', function() {
initProxyCheckbox();
initScalar();
});
document.addEventListener('DOMContentLoaded', initScalar);
} else {
initProxyCheckbox();
setTimeout(initScalar, 100);
}
// Also try on window load as fallback
window.addEventListener('load', function() {
initProxyCheckbox();
setTimeout(initScalar, 200);
});
</script>
docs/api/openapi.yaml
+506 -742
View File
File diff suppressed because it is too large Load Diff
docs/api/scalar-standalone.js
+35987
View File
File diff suppressed because one or more lines are too long
docs/api/scalar-style.css
+11911
View File
File diff suppressed because it is too large Load Diff
mkdocs.yml
+1 -2
View File
@@ -74,7 +74,6 @@ plugins:
- search
- minify:
minify_html: true
- swagger-ui-tag
nav:
- "Getting started": index.md
@@ -90,9 +89,9 @@ nav:
- "Installation": install.md
- "Configuration": config.md
- "Other things":
- "API Reference": api.md
- "FAQs": faq.md
- "Examples": examples.md
- "API Reference": /api/
- "Integrations + projects": integrations.md
- "Release notes": releases.md
- "Emojis 🥳 🎉": emojis.md