Skip to content

Commit 1e0daac

Browse files
KukksKukks
authored
feat(admin): OpenAPI/Swagger docs for the admin API (#10)
Add a dedicated admin OpenAPI spec (src/admin-openapi.ts) documenting every /admin/api endpoint — domains, addresses, API keys, blacklist, sessions, settings — with request/response shapes and error codes. Served on the admin port (behind the auth proxy) at GET /admin/api/docs (Redoc) and GET /admin/api/openapi.json, both mounted under /admin/api so they don't collide with the SPA catch-all. The SPA nav gains an "API Docs" link. The spec's version is sourced from the public openApiSpec so the two specs can't drift.
1 parent 8b07518 commit 1e0daac

7 files changed

Lines changed: 452 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## 0.2.6 - 2026-06-04
9+
10+
### Added
11+
- **Admin API documentation** — a dedicated OpenAPI/Swagger spec for the admin API, served on the admin port at `GET /admin/api/docs` (Redoc page) and `GET /admin/api/openapi.json`. Documents every admin endpoint (domains, addresses, API keys, blacklist, sessions, settings) with request/response shapes and error codes. The admin SPA nav gained an "API Docs ↗" link. The spec's version is sourced from the public spec so the two can't drift. (Kept separate from the public spec by design — the admin API runs on the loopback-bound admin port behind your auth proxy.)
12+
813
## 0.2.5 - 2026-06-04
914

1015
### Fixed

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@arkade-os/lnurl",
3-
"version": "0.2.5",
3+
"version": "0.2.6",
44
"description": "LNURL service for amountless Lightning receives via Arkade swaps",
55
"type": "module",
66
"main": "dist/index.js",

‎src/admin-api.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,27 @@ import type { AddressStatus } from "./db/types.js";
77
import type { SettingsService } from "./settings.js";
88
import { isSettingKey, SettingsError } from "./settings.js";
99
import type { AppConfig } from "./config.js";
10+
import { adminOpenApiSpec } from "./admin-openapi.js";
11+
12+
const ADMIN_DOCS_HTML = `<!DOCTYPE html>
13+
<html>
14+
<head>
15+
<title>LNURL Server - Admin API Docs</title>
16+
<meta charset="utf-8"/>
17+
<meta name="viewport" content="width=device-width, initial-scale=1">
18+
<style>body { margin: 0; }</style>
19+
</head>
20+
<body>
21+
<div id="redoc-container"></div>
22+
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
23+
<script>
24+
Redoc.init(${JSON.stringify(adminOpenApiSpec)}, {
25+
scrollYOffset: 0,
26+
hideDownloadButton: true,
27+
}, document.getElementById('redoc-container'));
28+
</script>
29+
</body>
30+
</html>`;
1031

1132
export interface AdminDeps {
1233
repos: Repositories;
@@ -168,5 +189,11 @@ export function createAdminApi(deps: AdminDeps): Router {
168189
res.json(settings.view());
169190
});
170191

192+
// ── API docs ──────────────────────────────────────────────
193+
// Served under /admin/api so they sit behind the same auth proxy and don't
194+
// collide with the SPA's catch-all (which serves index.html for non-/admin/api GETs).
195+
r.get("/openapi.json", (_req, res) => res.json(adminOpenApiSpec));
196+
r.get("/docs", (_req, res) => res.type("html").send(ADMIN_DOCS_HTML));
197+
171198
return r;
172199
}

0 commit comments

Comments
 (0)