Skip to content

Commit dc86600

Browse files
author
Faxbot Agent
committed
docs: point API reference to https://faxbot.net/api/v1 (ReDoc + Swagger alias); simplify API docs page; add mkdocs stubs
1 parent f93c8cb commit dc86600

File tree

9 files changed

+262
-164
lines changed

9 files changed

+262
-164
lines changed

‎.github/workflows/api-docs.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,8 @@ jobs:
201201
- name: Setup SSH key
202202
uses: webfactory/[email protected]
203203
with:
204-
ssh-private-key: ${{ secrets.FAXBOT_NET_DEPLOY_KEY }}
204+
# Prefer the secret name from API_DOCS_SETUP.md; fall back to legacy key if present
205+
ssh-private-key: ${{ secrets.FAXBOT_NET_DEPLOY_TOKEN || secrets.FAXBOT_NET_DEPLOY_KEY }}
205206

206207
- name: Checkout faxbot.net repo
207208
run: |
@@ -226,4 +227,4 @@ jobs:
226227
git commit -m "Update API documentation from faxbot@$(cd .. && git rev-parse --short HEAD) - Auto-generated $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
227228
git push origin main
228229
echo "✅ API documentation deployed to faxbot.net/api/"
229-
fi
230+
fi

‎docs/api-docs.html‎

Lines changed: 29 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -1,169 +1,40 @@
11
<!DOCTYPE html>
22
<html>
33
<head>
4-
<title>Faxbot API Documentation</title>
4+
<meta charset="utf-8">
5+
<title>Faxbot API Reference</title>
56
<style>
6-
body { font-family: Arial, sans-serif; margin: 0; padding: 20px; }
7-
.container { max-width: 1200px; margin: 0 auto; }
8-
.button {
9-
display: inline-block;
10-
padding: 12px 24px;
11-
background: #007bff;
12-
color: white;
13-
text-decoration: none;
14-
border-radius: 6px;
15-
margin: 10px 10px 10px 0;
16-
font-weight: bold;
17-
}
18-
.button:hover { background: #0056b3; }
19-
.success { background: #28a745; }
20-
.warning { background: #ffc107; color: #212529; }
21-
pre { background: #f8f9fa; padding: 15px; border-radius: 5px; overflow-x: auto; font-size: 12px; }
22-
.section { margin: 30px 0; padding: 20px; border: 1px solid #dee2e6; border-radius: 8px; }
23-
h1 { color: #333; }
24-
h2 { color: #666; border-bottom: 2px solid #eee; padding-bottom: 10px; }
7+
body { font-family: -apple-system, system-ui, Segoe UI, Roboto, Helvetica, Arial, sans-serif; line-height: 1.6; margin: 40px auto; max-width: 900px; padding: 0 16px; }
8+
h1, h2 { margin-top: 1.25rem; }
9+
a.button { display: inline-block; padding: 10px 16px; background: #2563eb; color: white; text-decoration: none; border-radius: 6px; margin: 6px 8px 6px 0; }
10+
a.secondary { background: #374151; }
11+
.muted { color: #6b7280; }
12+
.card { border: 1px solid #e5e7eb; border-radius: 8px; padding: 12px 16px; background: #f9fafb; }
2513
</style>
14+
<meta http-equiv="Cache-Control" content="no-store" />
15+
<meta http-equiv="Pragma" content="no-cache" />
16+
<meta http-equiv="Expires" content="0" />
2617
</head>
2718
<body>
28-
<div class="container">
29-
<h1>🚀 Faxbot API Documentation</h1>
30-
<p><strong>The first and only open-source, self-hostable fax API.</strong></p>
31-
32-
<div class="section">
33-
<h2>📋 Copy & Paste URLs (100% Working)</h2>
34-
<p>Use these URLs in any API documentation tool:</p>
35-
36-
<h3>JSON Format (Recommended)</h3>
37-
<pre>https://docs.faxbot.net/openapi.json</pre>
38-
<a href="https://petstore.swagger.io/?url=https://docs.faxbot.net/openapi.json" class="button">
39-
🔍 Open in Swagger UI
40-
</a>
41-
42-
<h3>YAML Format</h3>
43-
<pre>https://docs.faxbot.net/openapi.yaml</pre>
44-
<a href="https://petstore.swagger.io/?url=https://docs.faxbot.net/openapi.yaml" class="button">
45-
🔍 Open YAML in Swagger UI
46-
</a>
47-
</div>
48-
49-
<div class="section">
50-
<h2>🛠️ Tool-Specific Instructions</h2>
51-
52-
<h3>Postman</h3>
53-
<ol>
54-
<li>Click "Import" → "Link"</li>
55-
<li>Paste: <code>https://docs.faxbot.net/openapi.json</code></li>
56-
<li>Click "Continue" → "Import"</li>
57-
</ol>
58-
59-
<h3>Insomnia</h3>
60-
<ol>
61-
<li>File → Import/Export → Import Data → From URL</li>
62-
<li>Paste: <code>https://docs.faxbot.net/openapi.json</code></li>
63-
</ol>
64-
65-
<h3>Stoplight Studio</h3>
66-
<ol>
67-
<li>Create New Project → Import OpenAPI</li>
68-
<li>Paste: <code>https://docs.faxbot.net/openapi.json</code></li>
69-
</ol>
70-
71-
<h3>Redoc</h3>
72-
<ol>
73-
<li>Go to <a href="https://redocly.github.io/redoc/">redocly.github.io/redoc</a></li>
74-
<li>Add <code>?url=https://docs.faxbot.net/openapi.json</code> to the URL</li>
75-
</ol>
76-
</div>
77-
78-
<div class="section">
79-
<h2>⚡ Quick API Test</h2>
80-
<p>Test the API directly:</p>
81-
82-
<h3>Health Check</h3>
83-
<pre>curl http://localhost:8080/health</pre>
84-
85-
<h3>Send a Fax</h3>
86-
<pre>curl -X POST "http://localhost:8080/fax" \
87-
-H "X-API-Key: your_key_here" \
88-
-F "to=+15551234567" \
89-
-F "[email protected]"</pre>
90-
91-
<h3>Check Status</h3>
92-
<pre>curl -H "X-API-Key: your_key_here" \
93-
"http://localhost:8080/fax/{job_id}"</pre>
94-
</div>
95-
96-
<div class="section">
97-
<h2>📚 Core Endpoints</h2>
98-
<table style="width: 100%; border-collapse: collapse;">
99-
<tr style="background: #f8f9fa;">
100-
<th style="padding: 12px; text-align: left; border: 1px solid #dee2e6;">Method</th>
101-
<th style="padding: 12px; text-align: left; border: 1px solid #dee2e6;">Endpoint</th>
102-
<th style="padding: 12px; text-align: left; border: 1px solid #dee2e6;">Description</th>
103-
</tr>
104-
<tr>
105-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>POST</code></td>
106-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>/fax</code></td>
107-
<td style="padding: 12px; border: 1px solid #dee2e6;">Send a fax</td>
108-
</tr>
109-
<tr>
110-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>GET</code></td>
111-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>/fax/{id}</code></td>
112-
<td style="padding: 12px; border: 1px solid #dee2e6;">Get fax status</td>
113-
</tr>
114-
<tr>
115-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>GET</code></td>
116-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>/health</code></td>
117-
<td style="padding: 12px; border: 1px solid #dee2e6;">Health check</td>
118-
</tr>
119-
<tr>
120-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>GET</code></td>
121-
<td style="padding: 12px; border: 1px solid #dee2e6;"><code>/inbound</code></td>
122-
<td style="padding: 12px; border: 1px solid #dee2e6;">List received faxes</td>
123-
</tr>
124-
</table>
125-
</div>
126-
127-
<div class="section">
128-
<h2>🔧 If Nothing Works</h2>
129-
<p>Download the spec file directly:</p>
130-
<a href="/openapi.json" download="faxbot-openapi.json" class="button warning">
131-
📥 Download JSON
132-
</a>
133-
<a href="/openapi.yaml" download="faxbot-openapi.yaml" class="button warning">
134-
📥 Download YAML
135-
</a>
136-
<p>Then import the downloaded file into your tool.</p>
137-
</div>
138-
139-
<div id="test-status"></div>
19+
<h1>API Reference</h1>
20+
<p class="muted">The live, always‑up‑to‑date API reference is hosted on the website.</p>
21+
22+
<div class="card">
23+
<p>
24+
<a href="https://faxbot.net/api/v1/" class="button">📚 View API (ReDoc)</a>
25+
<a href="https://faxbot.net/api/v1/swagger" class="button secondary">🔍 Swagger UI</a>
26+
</p>
27+
<p>
28+
Spec files: <a href="https://faxbot.net/api/v1/openapi.json">JSON</a> · <a href="https://faxbot.net/api/v1/openapi.yaml">YAML</a>
29+
</p>
14030
</div>
14131

142-
<script>
143-
// Test if our URLs actually work
144-
function testUrl(url, format) {
145-
fetch(url)
146-
.then(response => {
147-
if (response.ok) {
148-
return response.text();
149-
}
150-
throw new Error(`HTTP ${response.status}`);
151-
})
152-
.then(data => {
153-
const statusDiv = document.getElementById('test-status');
154-
statusDiv.innerHTML += `<p style="color: #28a745;">✅ ${format} format is accessible and ready!</p>`;
155-
})
156-
.catch(error => {
157-
const statusDiv = document.getElementById('test-status');
158-
statusDiv.innerHTML += `<p style="color: #dc3545;">❌ ${format} format: ${error.message}</p>`;
159-
});
160-
}
161-
162-
// Test both formats
163-
setTimeout(() => {
164-
testUrl('https://docs.faxbot.net/openapi.json', 'JSON');
165-
testUrl('https://docs.faxbot.net/openapi.yaml', 'YAML');
166-
}, 1000);
167-
</script>
32+
<h2>Developers</h2>
33+
<p>For local preview, you can still use repo helpers:</p>
34+
<ul class="muted">
35+
<li><code>./scripts/regenerate-openapi-yaml.sh http://localhost:8080</code></li>
36+
<li><code>./scripts/preview-openapi-docs.sh</code> → <code>http://localhost:8081/swagger.html</code></li>
37+
</ul>
16838
</body>
16939
</html>
40+

‎docs/index.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ The first and only open‑source, self‑hostable fax API. Send faxes with a sin
1818
## Quick Links
1919

2020
### 🚀 Getting Started
21-
- **[📋 API Docs (Copy & Paste)](/api-docs.html)** - **WORKS WITH ANY TOOL**
22-
- **[API Reference](/api/)** - Complete REST API documentation
23-
- **[🔍 Interactive API Explorer](https://petstore.swagger.io/?url=https://docs.faxbot.net/openapi.json)** - Try the API
21+
- **[📚 API Reference (ReDoc)](https://faxbot.net/api/v1/)**
22+
- **[🔍 Swagger UI](https://faxbot.net/api/v1/swagger)**
23+
- **[🔍 Interactive API Explorer](https://petstore.swagger.io/?url=https://faxbot.net/api/v1/openapi.yaml)**
2424

2525
### 🤖 AI Integration
2626
- **[MCP Integration](/ai-integration/)** - Claude Desktop, Cursor, and custom assistants
@@ -44,4 +44,3 @@ Demo
4444
<video src="/assets/images/faxbot_demo.mp4" width="100%" autoplay loop muted playsinline controls>
4545
<a href="/assets/images/faxbot_demo.mp4">Watch the demo video</a>
4646
</video>
47-

‎mkdocs-test/docs/api.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: API
3+
---
4+
5+
# API Reference
6+
7+
The live API documentation is hosted on the website:
8+
9+
- ReDoc: https://faxbot.net/api/v1/
10+
- Swagger UI: https://faxbot.net/api/v1/swagger
11+
- Spec: https://faxbot.net/api/v1/openapi.yaml
12+
13+
For development, see the helpers in this repo:
14+
15+
```
16+
./scripts/regenerate-openapi-yaml.sh http://localhost:8080
17+
./scripts/preview-openapi-docs.sh
18+
```
19+

‎mkdocs-test/docs/email-fax.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Email to Fax
3+
---
4+
5+
# Email → Fax (Preview)
6+
7+
Email-to-fax is under development. Track plans in the repository and see the main docs site for updates.
8+

‎mkdocs-test/docs/setup.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Setup
3+
---
4+
5+
# Setup
6+
7+
Quick start: see deployment guide and environment templates in the main docs site.
8+
9+
- Docker Compose: docs/DEPLOYMENT.md
10+
- Environment: .env.example
11+

‎mkdocs-test/docs/tunnel.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Cloudflare Tunnel
3+
---
4+
5+
# Cloudflare Tunnel
6+
7+
Use Cloudflare Tunnel to expose your local Faxbot API securely for demos and provider webhooks. See the full guide in the Jekyll docs:
8+
9+
- docs: /networking/tunnel
10+

‎mkdocs-test/docs/vpn.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: VPN Support
3+
---
4+
5+
# VPN Support
6+
7+
Faxbot supports private networking and VPN topologies for SIP/Asterisk and secure inbound delivery. See deployment notes and the Jekyll docs for security guidance.
8+

0 commit comments

Comments
 (0)