feat(docs): internal API docs

bin/copy-dist.ts

@@ -29,7 +29,12 @@ const copy = async () => {
         fs.copySync(path.join("build", srcFile), destFile, { recursive: true });
     }
 
-    const filesToCopy = ["config-sample.ini", "tsconfig.webpack.json", "./src/etapi/etapi.openapi.yaml"];
+    const filesToCopy = [
+        "config-sample.ini",
+        "tsconfig.webpack.json",
+        "./src/etapi/etapi.openapi.yaml",
+        "./src/routes/api/openapi.json"
+    ];
     for (const file of filesToCopy) {
         log(`Copying ${file}`);
         await fs.copy(file, path.join(DEST_DIR, file));

bin/generate-openapi.ts

@@ -1,4 +1,7 @@
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
 import swaggerJsdoc from 'swagger-jsdoc';
+import fs from "fs";
 
 /*
  * Usage: npm run generate-openapi | tail -n1 > x.json
@@ -33,8 +36,10 @@ const options = {
 };
 
 const openapiSpecification = swaggerJsdoc(options);
-
-console.log(JSON.stringify(openapiSpecification));
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const outputPath = join(scriptDir, "..", "src", "routes", "api", "openapi.json");
+fs.writeFileSync(outputPath, JSON.stringify(openapiSpecification));
+console.log("Saved to ", outputPath);
 
 /**
  * @swagger

src/routes/api_docs.ts

@@ -1,4 +1,4 @@
-import type { Router } from "express";
+import type { Application, Router } from "express";
 import swaggerUi from "swagger-ui-express";
 import { readFile } from "fs/promises";
 import { fileURLToPath } from "url";
@@ -7,19 +7,29 @@ import yaml from "js-yaml";
 import type { JsonObject } from "swagger-ui-express";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const swaggerDocument = yaml.load(
+const etapiDocument = yaml.load(
     await readFile(join(__dirname, "../etapi/etapi.openapi.yaml"), "utf8")
 ) as JsonObject;
+const apiDocument = JSON.parse(await readFile(join(__dirname, "api", "openapi.json"), "utf-8"));
 
-function register(router: Router) {
-    router.use(
-        "/etapi",
-        swaggerUi.serve,
-        swaggerUi.setup(swaggerDocument, {
+function register(app: Application) {
+    app.use(
+        "/etapi/docs/",
+        swaggerUi.serveFiles(etapiDocument),
+        swaggerUi.setup(etapiDocument, {
             explorer: true,
             customSiteTitle: "TriliumNext ETAPI Documentation"
         })
     );
+
+    app.use(
+        "/api/docs/",
+        swaggerUi.serveFiles(apiDocument),
+        swaggerUi.setup(apiDocument, {
+            explorer: true,
+            customSiteTitle: "TriliumNext Internal API Documentation"
+        })
+    );
 }
 
 export default {