Tools/Notes
1
0
Fork 0
mirror of https://github.com/TriliumNext/Notes.git synced 2025-07-27 10:02:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document some note, branch, tree routes

Browse Source
This commit is contained in:
FliegendeWurst 2025-02-14 09:40:38 +01:00
parent 0f0ebed78a
commit a115214070
6 changed files with 297 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
bin/generate-openapi.js
View File

@ -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

1
src/routes/api/app_info.ts
View File

@ -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:

45
src/routes/api/branches.ts
View File

@ -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";

108
src/routes/api/notes.ts
View File

@ -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;

1
src/routes/api/sync.ts
View File

@ -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:

40
src/routes/api/tree.ts
View File

@ -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]);