feat: ✨ add OpenAPI and Swagger UI endpoints for API documentation

2026-07-21 11:12:11 +01:00
parent 1b3404155c
commit 7118f917b8
5 changed files with 2698 additions and 3 deletions
@@ -10,7 +10,8 @@ LABEL org.opencontainers.image.vendor="JDB-NET"
 WORKDIR /app
 COPY requirements.txt ./
 RUN pip install --no-cache-dir -r requirements.txt
-COPY app.py db.py ./
+COPY app.py db.py openapi.json ./
+COPY static/swagger.html ./static/
 COPY --from=frontend /app/static/dist ./static/dist
 ARG VERSION=unknown
 ENV VERSION=${VERSION}
@@ -3370,6 +3370,25 @@ def api_rack_export(rack_id):
                     as_attachment=True, download_name=f"{rack['name']}_rack.csv".replace(' ', '_'))


+# ── API documentation (OpenAPI + Swagger UI) ────────────────────────────────
+OPENAPI_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'openapi.json')
+SWAGGER_HTML = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'static', 'swagger.html')
+
+
+@app.route('/api/openapi.json')
+def api_openapi_spec():
+    if not os.path.isfile(OPENAPI_PATH):
+        return jsonify({'error': 'OpenAPI spec not found'}), 404
+    return send_file(OPENAPI_PATH, mimetype='application/json')
+
+
+@app.route('/api/docs')
+def api_docs():
+    if not os.path.isfile(SWAGGER_HTML):
+        return jsonify({'error': 'Swagger UI not found'}), 404
+    return send_file(SWAGGER_HTML)
+
+
 # ── SPA static files ──────────────────────────────────────────────────────────
 STATIC_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'static')
 DIST = os.path.join(STATIC_ROOT, 'dist')
@@ -135,10 +135,13 @@ async function delRole(id: number) {
    </div>

    <section v-if="tab === 'users'" class="mt-8">
-      <div class="mb-4 flex items-center justify-between">
+      <div class="mb-4 flex flex-wrap items-center justify-between gap-3">
        <h2 class="font-semibold text-accent">Users</h2>
+        <div class="flex flex-wrap gap-2">
+          <a href="/api/docs" target="_blank" rel="noopener noreferrer" class="btn-secondary text-sm">API documentation</a>
          <button v-if="auth.can('manage_users')" class="btn-primary text-sm" @click="openAddUser">Add user</button>
        </div>
+      </div>
      <ul class="space-y-2">
        <li
          class="hidden px-4 text-xs font-medium text-slate-500 sm:grid sm:grid-cols-[minmax(0,1fr)_8rem_13rem] sm:items-center sm:gap-4"
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>IPAM API Documentation</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui.css" />
+  <style>
+    html { box-sizing: border-box; overflow-y: scroll; }
+    *, *::before, *::after { box-sizing: inherit; }
+    body { margin: 0; background: #fafafa; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-bundle.js" charset="UTF-8"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
+  <script>
+    window.onload = function () {
+      SwaggerUIBundle({
+        url: "/api/openapi.json",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+        layout: "StandaloneLayout",
+        tryItOutEnabled: true,
+        persistAuthorization: true,
+      });
+    };
+  </script>
+</body>
+</html>