Merge pull request #1846 from FliegendeWurst/openapi-revive

OpenAPI documentation fixes

Author: eliandoran

apps/server/src/assets/openapi.json

@@ -124,14 +124,14 @@ function forceFullSync() {
  *               type: object
  *               properties:
  *                 entityChanges:
- *                   type: list
+ *                   type: array
  *                   items:
  *                     $ref: '#/components/schemas/EntityChange'
  *                 lastEntityChangeId:
  *                   type: integer
  *                   description: If `outstandingPullCount > 0`, pass this as parameter in your next request to continue.
  *                 outstandingPullCount:
- *                   type: int
+ *                   type: integer
  *                   example: 42
  *                   description: Number of changes not yet returned by the remote.
  *     security:
@@ -247,7 +247,7 @@ const partialRequests: Record<
  *                 type: string
  *                 description: Local instance ID
  *               entities:
- *                 type: list
+ *                 type: array
  *                 items:
  *                   $ref: '#/components/schemas/EntityChange'
  *     responses:

apps/server/src/routes/api/sync.ts

@@ -152,15 +152,15 @@ function getNotesAndBranchesAndAttributes(_noteIds: string[] | Set<string>) {
  *               type: object
  *               properties:
  *                 branches:
- *                   type: list
+ *                   type: array
  *                   items:
  *                     $ref: '#/components/schemas/Branch'
  *                 notes:
- *                   type: list
+ *                   type: array
  *                   items:
  *                     $ref: '#/components/schemas/Note'
  *                 attributes:
- *                   type: list
+ *                   type: array
  *                   items:
  *                     $ref: '#/components/schemas/Attribute'
  *     security:

apps/server/src/routes/api/tree.ts

@@ -62,6 +62,36 @@ function setPassword(req: Request, res: Response) {
     res.redirect("login");
 }
 
+/**
+ * @swagger
+ * /login:
+ *   post:
+ *     tags:
+ *       - auth
+ *     summary: Log in using password
+ *     description: This will give you a Trilium session, which is required for some other API endpoints. `totpToken` is only required if the user configured TOTP authentication.
+ *     operationId: login-normal
+ *     externalDocs:
+ *       description: HMAC calculation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/services/utils.ts#L62-L66
+ *     requestBody:
+ *       content:
+ *         application/x-www-form-urlencoded:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - password
+ *             properties:
+ *               password:
+ *                 type: string
+ *               totpToken:
+ *                 type: string
+ *     responses:
+ *       '200':
+ *         description: Successful operation
+ *       '401':
+ *         description: Password / TOTP mismatch
+ */
 function login(req: Request, res: Response) {
     if (openID.isOpenIDEnabled()) {
         res.oidc.login({

apps/server/src/routes/login.ts

@@ -1,2 +1,2 @@
 # attachments
-<figure class="table" style="width:100%;"><table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>attachmentId</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Unique ID (e.g. <code>qhC1vzU4nwSE</code>)</td></tr><tr><th><code>ownerId</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The unique ID of a row in&nbsp;<a class="reference-link" href="notes.md">notes</a>.</td></tr><tr><th><code>role</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The role of the attachment: <code>image</code> for images that are attached to a note.</td></tr><tr><th><code>mime</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The MIME type of the attachment (e.g. <code>image/png</code>)</td></tr><tr><th><code>title</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The title of the attachment.</td></tr><tr><th><code>isProtected</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Protected%20entities.md">protected</a>, <code>0</code> otherwise.</td></tr><tr><th><code>position</code></th><td>Integer</td><td>Non-null</td><td>0</td><td>Not sure where the position is relevant for attachments (saw it with values of 10 and 0).</td></tr><tr><th><code>blobId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>The corresponding <code>blobId</code> from the&nbsp;<a class="reference-link" href="blobs.md">blobs</a>&nbsp;table.</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Localized modification date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateScheduledForErasure</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>&nbsp;</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td>&nbsp;</td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>&nbsp;</td></tr></tbody></table></figure>
+<figure class="table" style="width:100%;"><table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Column Name</th><th>Data Type</th><th>Nullity</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><th><code>attachmentId</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Unique ID (e.g. <code>qhC1vzU4nwSE</code>)</td></tr><tr><th><code>ownerId</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The unique ID of a row in&nbsp;<a class="reference-link" href="notes.md">notes</a>.</td></tr><tr><th><code>role</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The role of the attachment: <code>image</code> for images that are attached to a note, <code>file</code> for uploaded files.</td></tr><tr><th><code>mime</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The MIME type of the attachment (e.g. <code>image/png</code>)</td></tr><tr><th><code>title</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>The title of the attachment.</td></tr><tr><th><code>isProtected</code></th><td>Integer</td><td>Non-null</td><td>0</td><td><code>1</code> if the entity is <a href="../Protected%20entities.md">protected</a>, <code>0</code> otherwise.</td></tr><tr><th><code>position</code></th><td>Integer</td><td>Non-null</td><td>0</td><td>Not sure where the position is relevant for attachments (saw it with values of 10 and 0).</td></tr><tr><th><code>blobId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>The corresponding <code>blobId</code> from the&nbsp;<a class="reference-link" href="blobs.md">blobs</a>&nbsp;table.</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Localized modification date (e.g. <code>2023-11-08 18:43:44.204+0200</code>)</td></tr><tr><th><code>utcDateModified</code></th><td>Text</td><td>Non-null</td><td>&nbsp;</td><td>Modification date in UTC format (e.g. <code>2023-11-08 16:43:44.204Z</code>)</td></tr><tr><th><code>utcDateScheduledForErasure</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>&nbsp;</td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td>&nbsp;</td><td><code>1</code> if the entity is <a href="../Deleted%20notes.md">deleted</a>, <code>0</code> otherwise.</td></tr><tr><th><code>deleteId</code></th><td>Text</td><td>Nullable</td><td><code>null</code></td><td>&nbsp;</td></tr></tbody></table></figure>

docs/Developer Guide/Developer Guide/Old documentation/Development and architecture/Database/attachments.md

@@ -16,6 +16,7 @@
     "server:start-prod": "nx run server:start-prod",
     "electron:build": "nx build desktop",
     "chore:ci-update-nightly-version": "tsx ./scripts/update-nightly-version.ts",
+    "chore:generate-openapi": "tsx ./scripts/generate-openapi.ts",
     "chore:update-build-info": "tsx ./scripts/update-build-info.ts",
     "chore:update-version": "tsx ./scripts/update-version.ts",
     "test": "pnpm nx run-many -t test",

package.json

@@ -4,18 +4,24 @@ import swaggerJsdoc from "swagger-jsdoc";
 import fs from "fs";
 
 /*
- * Usage: npm run generate-openapi | tail -n1 > x.json
+ * Usage: npm run chore:generate-openapi
+ * Output: ./apps/server/src/assets/openapi.json
  *
  * Inspect generated file by opening it in https://editor-next.swagger.io/
  *
  */
 
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const outputPath = join(scriptDir, "..", "apps", "server", "src", "assets", "openapi.json");
+
+const packageJson = JSON.parse(fs.readFileSync(join(scriptDir, "..", "package.json"), 'utf8'));
+
 const options = {
     definition: {
         openapi: "3.1.1",
         info: {
             title: "Trilium Notes - Sync server API",
-            version: "0.96.6",
+            version: packageJson["version"],
             description:
                 "This is the internal sync server API used by Trilium Notes / TriliumNext Notes.\n\n_If you're looking for the officially supported External Trilium API, see [here](https://triliumnext.github.io/Docs/Wiki/etapi.html)._\n\nThis page does not yet list all routes. For a full list, see the [route controller](https://github.com/TriliumNext/Notes/blob/v0.91.6/src/routes/routes.ts).",
             contact: {
@@ -30,18 +36,17 @@ const options = {
     },
     apis: [
         // Put individual files here to have them ordered first.
-        "./src/routes/api/setup.ts",
+        "./apps/server/src/routes/api/setup.ts",
         // all other files
-        "./src/routes/api/*.ts",
-        "./bin/generate-openapi.js"
+        "./apps/server/src/routes/api/*.ts",
+        "./apps/server/src/routes/*.ts",
+        "./scripts/generate-openapi.ts"
     ]
 };
 
 const openapiSpecification = swaggerJsdoc(options);
-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);
+console.log("Saved to", outputPath);
 
 /**
  * @swagger
@@ -67,7 +72,7 @@ console.log("Saved to ", outputPath);
  *           $ref: "#/components/schemas/NoteId"
  *         type:
  *           type: string
- *           enum: ["attribute", "relation"]
+ *           enum: ["label", "relation"]
  *         name:
  *           type: string
  *           example: "internalLink"
@@ -99,6 +104,7 @@ console.log("Saved to ", outputPath);
  *           $ref: "#/components/schemas/UtcDateTime"
  *     Branch:
  *       type: object
+ *       required: ["branchId", "noteId", "parentNoteId", "notePosition"]
  *       properties:
  *         branchId:
  *           $ref: "#/components/schemas/BranchId"
@@ -141,6 +147,7 @@ console.log("Saved to ", outputPath);
  *           description: Encoded entity data. Object has one property for each database column.
  *     Note:
  *       type: object
+ *       required: ["noteId", "title", "isProtected", "type", "mime", "blobId"]
  *       properties:
  *         noteId:
  *           $ref: "#/components/schemas/NoteId"