Refine open API docs
This commit is contained in:
binwiederhier
44
docs/api.md
44
docs/api.md
@@ -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).
|
||||
@@ -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>
|
||||
File diff suppressed because it is too large
Load Diff
35987
docs/api/scalar-standalone.js
Normal file
35987
docs/api/scalar-standalone.js
Normal file
File diff suppressed because one or more lines are too long
11911
docs/api/scalar-style.css
Normal file
11911
docs/api/scalar-style.css
Normal file
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user