Document some note, branch, tree routes

bin/generate-openapi.js

@@ -43,12 +43,78 @@ console.log(JSON.stringify(openapiSpecification));
  *     description: Authentication
  *   - name: sync
  *     description: Synchronization
+ *   - name: data
  */
 
 /**
  * @swagger
  * components:
  *   schemas:
+ *     Attribute:
+ *       type: object
+ *       properties:
+ *         attributeId:
+ *           type: string
+ *           example: "4G1DPrI58PAb"
+ *         noteId:
+ *           $ref: "#/components/schemas/NoteId"
+ *         type:
+ *           type: string
+ *           enum: ["attribute", "relation"]
+ *         name:
+ *           type: string
+ *           example: "internalLink"
+ *         value:
+ *           type: string
+ *           example: "hA8aHSpTRdZ6"
+ *           description: "If type = \"relation\", a note ID. Otherwise, the attribute content."
+ *         position:
+ *           type: integer
+ *           example: 20
+ *         isInheritable:
+ *           type: boolean
+ *     Blob:
+ *       type: object
+ *       properties:
+ *         blobId:
+ *           type: string
+ *           example: "8iqMIB8eiY1tPYmElfjm"
+ *         content:
+ *           type:
+ *             - string
+ *             - 'null'
+ *           description: "`null` if not text."
+ *         contentLength:
+ *           type: integer
+ *         dateModified:
+ *           $ref: "#/components/schemas/DateTime"
+ *         utcDateModified:
+ *           $ref: "#/components/schemas/UtcDateTime"
+ *     Branch:
+ *       type: object
+ *       properties:
+ *         branchId:
+ *           $ref: "#/components/schemas/BranchId"
+ *         noteId:
+ *           $ref: "#/components/schemas/NoteId"
+ *         parentNoteId:
+ *           $ref: "#/components/schemas/NoteId"
+ *         notePosition:
+ *           type: integer
+ *           example: 20
+ *         prefix:
+ *           type:
+ *             - string
+ *             - 'null'
+ *         isExpanded:
+ *           type: boolean
+ *     BranchId:
+ *       type: string
+ *       example: "WUjhaGp4EKah_ur11rSfHkzeV"
+ *       description: Equal to `{parentNoteId}_{noteId}`
+ *     DateTime:
+ *       type: string
+ *       example: "2025-02-14 08:19:59.203+0100"
  *     EntityChange:
  *       type: object
  *       properties:
@@ -66,9 +132,45 @@ console.log(JSON.stringify(openapiSpecification));
  *         entity:
  *           type: object
  *           description: Encoded entity data. Object has one property for each database column.
+ *     Note:
+ *       type: object
+ *       properties:
+ *         noteId:
+ *           $ref: "#/components/schemas/NoteId"
+ *         title:
+ *           type: string
+ *         isProtected:
+ *           type: boolean
+ *         type:
+ *           type: string
+ *           example: "text"
+ *           enum: ["text", "code", "render", "file", "image", "search", "relationMap", "book", "noteMap", "mermaid", "canvas", "webView", "launcher", "doc", "contentWidget", "mindMap", "geoMap"]
+ *           description: "[Reference list](https://github.com/TriliumNext/Notes/blob/v0.91.6/src/services/note_types.ts)"
+ *         mime:
+ *           type: string
+ *           example: "text/html"
+ *         blobId:
+ *           type: string
+ *           example: "z4PhNX7vuL3xVChQ1m2A"
+ *     NoteId:
+ *       type: string
+ *       example: "ur11rSfHkzeV"
+ *       description: "12-character note ID. Special values: \"none\"`, `\"root\"."
+ *     Timestamps:
+ *       type: object
+ *       properties:
+ *         dateCreated:
+ *           $ref: "#/components/schemas/DateTime"
+ *         dateModified:
+ *           $ref: "#/components/schemas/DateTime"
+ *         utcDateCreated:
+ *           $ref: "#/components/schemas/UtcDateTime"
+ *         utcDateModified:
+ *           $ref: "#/components/schemas/UtcDateTime"
  *     UtcDateTime:
  *       type: string
  *       example: "2025-02-13T07:42:47.698Z"
+ *       description: "Result of `new Date().toISOString().replace('T', ' ')`"
  *   securitySchemes:
  *     user-password:
  *       type: apiKey

src/routes/api/app_info.ts

@@ -13,6 +13,7 @@ import appInfo from "../../services/app_info.js";
  *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/services/app_info.ts
  *     responses:
  *       '200':
+ *         description: Installation info
  *         content:
  *           application/json:
  *             schema:

src/routes/api/branches.ts

@@ -186,6 +186,51 @@ function setExpandedForSubtree(req: Request) {
     };
 }
 
+/**
+ * @swagger
+ * /api/branches/{branchId}:
+ *   delete:
+ *     summary: Delete branch (note clone)
+ *     operationId: branches-delete
+ *     parameters:
+ *       - name: branchId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           $ref: "#/components/schemas/BranchId"
+ *       - name: taskId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Task group identifier
+ *       - name: eraseNotes
+ *         in: query
+ *         schema:
+ *           type: boolean
+ *         required: false
+ *         description: Whether to erase the note immediately
+ *       - name: last
+ *         in: query
+ *         schema:
+ *           type: boolean
+ *         required: true
+ *         description: Whether this is the last request of this task group
+ *     responses:
+ *       '200':
+ *         description: Branch successfully deleted
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 noteDeleted:
+ *                   type: boolean
+ *                   description: Whether the last note clone was deleted
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function deleteBranch(req: Request) {
     const last = req.query.last === "true";
     const eraseNotes = req.query.eraseNotes === "true";

src/routes/api/notes.ts

@@ -14,14 +14,85 @@ import type { Request } from "express";
 import type BBranch from "../../becca/entities/bbranch.js";
 import type { AttributeRow } from "../../becca/entities/rows.js";
 
+/**
+ * @swagger
+ * /api/notes/{noteId}:
+ *   get:
+ *     summary: Retrieve note metadata
+ *     operationId: notes-get
+ *     parameters:
+ *       - name: noteId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           $ref: "#/components/schemas/NoteId"
+ *     responses:
+ *       '200':
+ *         description: Note metadata
+ *         content:
+ *           application/json:
+ *             schema:
+ *              allOf:
+ *                - $ref: '#/components/schemas/Note'
+ *                - $ref: "#/components/schemas/Timestamps"
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function getNote(req: Request) {
     return becca.getNoteOrThrow(req.params.noteId);
 }
 
+/**
+ * @swagger
+ * /api/notes/{noteId}/blob:
+ *   get:
+ *     summary: Retrieve note content
+ *     operationId: notes-blob
+ *     parameters:
+ *       - name: noteId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           $ref: "#/components/schemas/NoteId"
+ *     responses:
+ *       '304':
+ *         description: Note content
+ *         content:
+ *           application/json:
+ *             schema:
+ *              $ref: '#/components/schemas/Blob'
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function getNoteBlob(req: Request) {
     return blobService.getBlobPojo("notes", req.params.noteId);
 }
 
+/**
+ * @swagger
+ * /api/notes/{noteId}/metadata:
+ *   get:
+ *     summary: Retrieve note metadata (limited to timestamps)
+ *     operationId: notes-metadata
+ *     parameters:
+ *       - name: noteId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           $ref: "#/components/schemas/NoteId"
+ *     responses:
+ *       '200':
+ *         description: Note metadata
+ *         content:
+ *           application/json:
+ *             schema:
+ *              $ref: "#/components/schemas/Timestamps"
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function getNoteMetadata(req: Request) {
     const note = becca.getNoteOrThrow(req.params.noteId);
 
@@ -62,6 +133,43 @@ function updateNoteData(req: Request) {
     return noteService.updateNoteData(noteId, content, attachments);
 }
 
+/**
+ * @swagger
+ * /api/notes/{noteId}:
+ *   delete:
+ *     summary: Delete note
+ *     operationId: notes-delete
+ *     parameters:
+ *       - name: noteId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           $ref: "#/components/schemas/NoteId"
+ *       - name: taskId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Task group identifier
+ *       - name: eraseNotes
+ *         in: query
+ *         schema:
+ *           type: boolean
+ *         required: false
+ *         description: Whether to erase the note immediately
+ *       - name: last
+ *         in: query
+ *         schema:
+ *           type: boolean
+ *         required: true
+ *         description: Whether this is the last request of this task group
+ *     responses:
+ *       '200':
+ *         description: Note successfully deleted
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function deleteNote(req: Request) {
     const noteId = req.params.noteId;
     const taskId = req.query.taskId;

src/routes/api/sync.ts

@@ -116,6 +116,7 @@ function forceFullSync() {
  *         description: Marker to identify this request in server log
  *     responses:
  *       '200':
+ *         description: Sync changes, limited to approximately one megabyte.
  *         content:
  *           application/json:
  *             schema:

src/routes/api/tree.ts

@@ -127,6 +127,46 @@ function getNotesAndBranchesAndAttributes(_noteIds: string[] | Set<string>) {
     };
 }
 
+/**
+ * @swagger
+ * /api/tree:
+ *   get:
+ *     summary: Retrieve tree data
+ *     operationId: tree
+ *     externalDocs:
+ *       description: Server implementation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/routes/api/tree.ts
+ *     parameters:
+ *       - in: query
+ *         name: subTreeNoteId
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Limit tree data to this note and descendants
+ *     responses:
+ *       '200':
+ *         description: Notes, branches and attributes
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 branches:
+ *                   type: list
+ *                   items:
+ *                     $ref: '#/components/schemas/Branch'
+ *                 notes:
+ *                   type: list
+ *                   items:
+ *                     $ref: '#/components/schemas/Note'
+ *                 attributes:
+ *                   type: list
+ *                   items:
+ *                     $ref: '#/components/schemas/Attribute'
+ *     security:
+ *       - session: []
+ *     tags: ["data"]
+ */
 function getTree(req: Request) {
     const subTreeNoteId = typeof req.query.subTreeNoteId === "string" ? req.query.subTreeNoteId : "root";
     const collectedNoteIds = new Set<string>([subTreeNoteId]);