Added Openapi spec/swagger UI - added swagger to python requirements.txt
This commit is contained in:
gitglubber
31
docs/api.md
Normal file
31
docs/api.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 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 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**.
|
||||
|
||||
To use your own ntfy instance, edit `docs/swagger_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 Swagger UI 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.
|
||||
|
||||
<swagger-ui src="swagger_api/openapi.yaml"/>
|
||||
586
docs/swagger_api/index.html
Normal file
586
docs/swagger_api/index.html
Normal file
@@ -0,0 +1,586 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<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="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css">
|
||||
<style>
|
||||
* {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
||||
background: #f8f9fa;
|
||||
}
|
||||
|
||||
/* Header matching docs.ntfy.sh */
|
||||
.header {
|
||||
background: linear-gradient(to right, #317f6f, #14b8a6);
|
||||
padding: 16px 20px;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.header-content {
|
||||
max-width: 1400px;
|
||||
margin: 0 auto;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 20px;
|
||||
justify-content: space-between;
|
||||
}
|
||||
|
||||
.header-logo {
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.header-text {
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
.header-text h1 {
|
||||
font-size: 24px;
|
||||
font-weight: 700;
|
||||
margin: 0;
|
||||
color: white;
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
.header-text p {
|
||||
font-size: 13px;
|
||||
margin: 2px 0 0 0;
|
||||
color: rgba(255, 255, 255, 0.9);
|
||||
}
|
||||
|
||||
.header-links {
|
||||
display: flex;
|
||||
gap: 20px;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.header-links a {
|
||||
color: white;
|
||||
text-decoration: none;
|
||||
font-size: 14px;
|
||||
font-weight: 500;
|
||||
opacity: 0.9;
|
||||
transition: opacity 0.2s;
|
||||
}
|
||||
|
||||
.header-links a:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
/* Server config section */
|
||||
.config-section {
|
||||
background: white;
|
||||
border-bottom: 1px solid #e5e7eb;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.config-content {
|
||||
max-width: 1400px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
.config-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 15px;
|
||||
flex-wrap: wrap;
|
||||
margin-bottom: 15px;
|
||||
}
|
||||
|
||||
.config-row:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
.config-label {
|
||||
font-weight: 600;
|
||||
color: #1a1a1a;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.config-input {
|
||||
padding: 8px 12px;
|
||||
border: 1px solid #d1d5db;
|
||||
border-radius: 6px;
|
||||
font-size: 14px;
|
||||
width: 300px;
|
||||
font-family: inherit;
|
||||
}
|
||||
|
||||
.config-input:focus {
|
||||
outline: none;
|
||||
border-color: #317f6f;
|
||||
box-shadow: 0 0 0 3px rgba(49, 127, 111, 0.1);
|
||||
}
|
||||
|
||||
.config-button {
|
||||
background: #317f6f;
|
||||
color: white;
|
||||
border: none;
|
||||
padding: 8px 20px;
|
||||
border-radius: 6px;
|
||||
cursor: pointer;
|
||||
font-weight: 600;
|
||||
font-size: 14px;
|
||||
font-family: inherit;
|
||||
transition: background 0.2s;
|
||||
}
|
||||
|
||||
.config-button:hover {
|
||||
background: #266959;
|
||||
}
|
||||
|
||||
.info-text {
|
||||
color: #6b7280;
|
||||
font-size: 13px;
|
||||
line-height: 1.5;
|
||||
}
|
||||
|
||||
.info-text code {
|
||||
background: #f3f4f6;
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-family: 'Monaco', 'Menlo', monospace;
|
||||
font-size: 12px;
|
||||
color: #dc2626;
|
||||
}
|
||||
|
||||
/* Hide default topbar and servers dropdown */
|
||||
.topbar {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
.swagger-ui .servers {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
/* Swagger UI container */
|
||||
.swagger-container {
|
||||
max-width: 1400px;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
/* Swagger UI theme overrides */
|
||||
.swagger-ui .info {
|
||||
margin: 20px 0;
|
||||
}
|
||||
|
||||
.swagger-ui .info h1,
|
||||
.swagger-ui .info h2,
|
||||
.swagger-ui .info h3,
|
||||
.swagger-ui .info h4,
|
||||
.swagger-ui .info h5 {
|
||||
color: #1a1a1a !important;
|
||||
}
|
||||
|
||||
.swagger-ui .info p,
|
||||
.swagger-ui .info div {
|
||||
color: #374151 !important;
|
||||
}
|
||||
|
||||
.swagger-ui h2,
|
||||
.swagger-ui h3,
|
||||
.swagger-ui h4,
|
||||
.swagger-ui h5 {
|
||||
color: #1a1a1a !important;
|
||||
}
|
||||
|
||||
.swagger-ui p,
|
||||
.swagger-ui span,
|
||||
.swagger-ui div {
|
||||
color: #374151 !important;
|
||||
}
|
||||
|
||||
/* Authorize button */
|
||||
.swagger-ui .btn.authorize {
|
||||
background: #317f6f !important;
|
||||
color: white !important;
|
||||
border: none;
|
||||
padding: 10px 20px;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.swagger-ui .btn.authorize:hover {
|
||||
background: #266959 !important;
|
||||
}
|
||||
|
||||
/* Operation blocks */
|
||||
.swagger-ui .opblock {
|
||||
background: #ffffff;
|
||||
border: 1px solid #d1d5db;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 12px;
|
||||
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-summary {
|
||||
border-color: #d1d5db;
|
||||
padding: 12px;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-summary-description {
|
||||
color: #374151 !important;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-section-header {
|
||||
background: #f9fafb;
|
||||
border-color: #e5e7eb;
|
||||
color: #1a1a1a !important;
|
||||
}
|
||||
|
||||
/* Method colors */
|
||||
.swagger-ui .opblock.get {
|
||||
border-color: #317f6f;
|
||||
}
|
||||
.swagger-ui .opblock.get .opblock-summary-method {
|
||||
background: #317f6f;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.post {
|
||||
border-color: #3b82f6;
|
||||
}
|
||||
.swagger-ui .opblock.post .opblock-summary-method {
|
||||
background: #3b82f6;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.put {
|
||||
border-color: #f59e0b;
|
||||
}
|
||||
.swagger-ui .opblock.put .opblock-summary-method {
|
||||
background: #f59e0b;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.delete {
|
||||
border-color: #ef4444;
|
||||
}
|
||||
.swagger-ui .opblock.delete .opblock-summary-method {
|
||||
background: #ef4444;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.patch {
|
||||
border-color: #8b5cf6;
|
||||
}
|
||||
.swagger-ui .opblock.patch .opblock-summary-method {
|
||||
background: #8b5cf6;
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.swagger-ui table {
|
||||
color: #1a1a1a !important;
|
||||
}
|
||||
|
||||
.swagger-ui table thead tr {
|
||||
background: #f9fafb;
|
||||
}
|
||||
|
||||
.swagger-ui table thead th {
|
||||
color: #1a1a1a !important;
|
||||
border-bottom: 2px solid #e5e7eb;
|
||||
}
|
||||
|
||||
.swagger-ui table tbody td {
|
||||
color: #374151 !important;
|
||||
border-bottom: 1px solid #e5e7eb;
|
||||
}
|
||||
|
||||
/* Inputs */
|
||||
.swagger-ui input[type="text"],
|
||||
.swagger-ui input[type="password"],
|
||||
.swagger-ui textarea {
|
||||
background: white !important;
|
||||
border: 1px solid #d1d5db !important;
|
||||
color: #1a1a1a !important;
|
||||
}
|
||||
|
||||
.swagger-ui input[type="text"]:focus,
|
||||
.swagger-ui input[type="password"]:focus,
|
||||
.swagger-ui textarea:focus {
|
||||
border-color: #317f6f !important;
|
||||
}
|
||||
|
||||
/* Try it out button */
|
||||
.swagger-ui .btn.try-out__btn {
|
||||
background: #317f6f !important;
|
||||
color: white !important;
|
||||
}
|
||||
|
||||
.swagger-ui .try-out button {
|
||||
background: #317f6f !important;
|
||||
color: white !important;
|
||||
}
|
||||
|
||||
/* Code blocks and responses */
|
||||
.swagger-ui .microlight {
|
||||
background: #0a2e23 !important;
|
||||
color: #ccfbf1 !important;
|
||||
border-radius: 6px !important;
|
||||
padding: 16px !important;
|
||||
font-size: 14px !important;
|
||||
line-height: 1.6 !important;
|
||||
}
|
||||
|
||||
.swagger-ui pre {
|
||||
background: #0a2e23 !important;
|
||||
color: #ccfbf1 !important;
|
||||
border-radius: 6px !important;
|
||||
padding: 16px !important;
|
||||
}
|
||||
|
||||
.swagger-ui pre code {
|
||||
background: transparent !important;
|
||||
color: #ccfbf1 !important;
|
||||
padding: 0 !important;
|
||||
}
|
||||
|
||||
.swagger-ui code {
|
||||
background: #e6fffa !important;
|
||||
color: #134e4a !important;
|
||||
padding: 2px 6px !important;
|
||||
border-radius: 4px !important;
|
||||
font-family: 'Monaco', 'Menlo', 'Courier New', monospace !important;
|
||||
font-size: 13px !important;
|
||||
font-weight: 600 !important;
|
||||
}
|
||||
|
||||
/* Responsive */
|
||||
@media (max-width: 768px) {
|
||||
.header-content {
|
||||
flex-direction: column;
|
||||
gap: 10px;
|
||||
text-align: center;
|
||||
}
|
||||
.header-links {
|
||||
flex-wrap: wrap;
|
||||
justify-content: center;
|
||||
}
|
||||
.config-row {
|
||||
flex-direction: column;
|
||||
align-items: stretch;
|
||||
}
|
||||
.config-input {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Header -->
|
||||
<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;">
|
||||
</a>
|
||||
<div class="header-text">
|
||||
<h1>ntfy</h1>
|
||||
<p>API Reference</p>
|
||||
</div>
|
||||
<div class="header-links">
|
||||
<a href="/">Documentation Home</a>
|
||||
<a href="https://ntfy.sh">ntfy.sh</a>
|
||||
<a href="https://github.com/binwiederhier/ntfy">GitHub</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Server Configuration -->
|
||||
<div class="config-section">
|
||||
<div class="config-content">
|
||||
<div class="config-row">
|
||||
<span class="config-label">Server URL:</span>
|
||||
<input type="text" id="server-url" class="config-input" value="" placeholder="https://ntfy.sh">
|
||||
<button class="config-button" onclick="updateServer()">Update Server</button>
|
||||
</div>
|
||||
<div class="config-row">
|
||||
<span class="info-text">
|
||||
<strong>Authentication:</strong> Click the <strong>Authorize</strong> button (lock icon) in the top right to add your access token (e.g., <code>tk_your_token_here</code>).<br>
|
||||
<strong>Try It Out:</strong> Click "Try it out" on any endpoint to test it directly in your browser.
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Swagger UI -->
|
||||
<div class="swagger-container">
|
||||
<div id="swagger-ui"></div>
|
||||
</div>
|
||||
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js" charset="UTF-8"></script>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
|
||||
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
|
||||
<script>
|
||||
// Global server URL variable
|
||||
let customServerUrl = 'https://ntfy.sh';
|
||||
|
||||
function updateServer() {
|
||||
const input = document.getElementById('server-url');
|
||||
let url = input.value.trim();
|
||||
|
||||
// Remove trailing slash
|
||||
if (url.endsWith('/')) {
|
||||
url = url.slice(0, -1);
|
||||
}
|
||||
|
||||
// Validate URL
|
||||
try {
|
||||
new URL(url);
|
||||
customServerUrl = url;
|
||||
|
||||
// Update the input value
|
||||
input.value = url;
|
||||
|
||||
// Show confirmation
|
||||
alert('Server URL updated to: ' + url + '\n\nAll API requests will now use this server.');
|
||||
|
||||
// Reload the page to apply changes
|
||||
location.reload();
|
||||
} catch (e) {
|
||||
alert('Please enter a valid URL (e.g., https://ntfy.sh or http://localhost:8080)');
|
||||
}
|
||||
}
|
||||
|
||||
// Clear all Swagger UI persisted data on page load
|
||||
function clearSwaggerUIStorage() {
|
||||
const keysToRemove = [];
|
||||
for (let i = 0; i < localStorage.length; i++) {
|
||||
const key = localStorage.key(i);
|
||||
if (key && (key.startsWith('swagger') || key.includes('authorized') || key.includes('auth'))) {
|
||||
keysToRemove.push(key);
|
||||
}
|
||||
}
|
||||
keysToRemove.forEach(key => localStorage.removeItem(key));
|
||||
|
||||
const sessionKeysToRemove = [];
|
||||
for (let i = 0; i < sessionStorage.length; i++) {
|
||||
const key = sessionStorage.key(i);
|
||||
if (key && (key.startsWith('swagger') || key.includes('authorized') || key.includes('auth'))) {
|
||||
sessionKeysToRemove.push(key);
|
||||
}
|
||||
}
|
||||
sessionKeysToRemove.forEach(key => sessionStorage.removeItem(key));
|
||||
}
|
||||
|
||||
clearSwaggerUIStorage();
|
||||
|
||||
window.addEventListener('beforeunload', function() {
|
||||
clearSwaggerUIStorage();
|
||||
if (window.ui) {
|
||||
const auths = window.ui.authActions;
|
||||
if (auths) {
|
||||
auths.logout();
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
function clearAllParameters() {
|
||||
const inputs = document.querySelectorAll('.swagger-ui input[type="text"], .swagger-ui input[type="password"], .swagger-ui textarea, .swagger-ui input[type="url"], .swagger-ui input[type="email"]');
|
||||
inputs.forEach(input => {
|
||||
input.value = '';
|
||||
});
|
||||
|
||||
const fileInputs = document.querySelectorAll('.swagger-ui input[type="file"]');
|
||||
fileInputs.forEach(input => {
|
||||
input.value = '';
|
||||
});
|
||||
|
||||
const checkboxes = document.querySelectorAll('.swagger-ui input[type="checkbox"]');
|
||||
checkboxes.forEach(box => {
|
||||
box.checked = false;
|
||||
});
|
||||
|
||||
const selects = document.querySelectorAll('.swagger-ui select');
|
||||
selects.forEach(select => {
|
||||
select.selectedIndex = 0;
|
||||
});
|
||||
}
|
||||
|
||||
window.onload = function() {
|
||||
fetch('./openapi.yaml')
|
||||
.then(response => response.text())
|
||||
.then(yamlSpec => {
|
||||
const spec = jsyaml.load(yamlSpec);
|
||||
|
||||
// Remove example values from parameters to prevent Swagger UI from using them as defaults
|
||||
function removeExamples(obj) {
|
||||
if (!obj || typeof obj !== 'object') return;
|
||||
|
||||
if (Array.isArray(obj)) {
|
||||
obj.forEach(removeExamples);
|
||||
return;
|
||||
}
|
||||
|
||||
for (const key in obj) {
|
||||
if (key === 'example' || key === 'examples') {
|
||||
delete obj[key];
|
||||
} else {
|
||||
removeExamples(obj[key]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
removeExamples(spec);
|
||||
|
||||
// Initialize Swagger UI
|
||||
const ui = SwaggerUIBundle({
|
||||
spec: spec,
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
SwaggerUIStandalonePreset
|
||||
],
|
||||
plugins: [
|
||||
SwaggerUIBundle.plugins.DownloadUrl
|
||||
],
|
||||
layout: "StandaloneLayout",
|
||||
defaultModelsExpandDepth: 1,
|
||||
defaultModelExpandDepth: 1,
|
||||
docExpansion: "list",
|
||||
filter: true,
|
||||
tryItOutEnabled: true,
|
||||
persistAuthorization: true,
|
||||
validatorUrl: null,
|
||||
displayRequestDuration: true,
|
||||
displayOperationId: false,
|
||||
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
|
||||
requestInterceptor: (request) => {
|
||||
// Replace base URL with custom server URL
|
||||
if (request.url && request.url.startsWith('/')) {
|
||||
request.url = customServerUrl + request.url;
|
||||
}
|
||||
return request;
|
||||
},
|
||||
responseInterceptor: (response) => {
|
||||
return response;
|
||||
}
|
||||
});
|
||||
|
||||
window.ui = ui;
|
||||
|
||||
// Clear all parameters after UI loads
|
||||
setTimeout(clearAllParameters, 100);
|
||||
setTimeout(clearAllParameters, 500);
|
||||
setTimeout(clearAllParameters, 1000);
|
||||
})
|
||||
.catch(error => {
|
||||
console.error('Error loading spec:', error);
|
||||
document.getElementById('swagger-ui').innerHTML =
|
||||
'<div style="padding: 20px; color: red;">Error loading OpenAPI spec. Please make sure openapi.yaml exists.</div>';
|
||||
});
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
2574
docs/swagger_api/openapi.yaml
Normal file
2574
docs/swagger_api/openapi.yaml
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user