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

Merge pull request #1846 from FliegendeWurst/openapi-revive

Browse Source 
OpenAPI documentation fixes
This commit is contained in:
Elian Doran 2025-05-04 00:24:15 +03:00 committed by GitHub
commit 1652481e42
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 55 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
apps/server/src/assets/openapi.json
View File

File diff suppressed because one or more lines are too long

6
apps/server/src/routes/api/sync.ts
View File

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

6
apps/server/src/routes/api/tree.ts
View File

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

30
apps/server/src/routes/login.ts
View File

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

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

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

1
package.json
View File

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

23
_regroup/bin/generate-openapi.ts → scripts/generate-openapi.ts
View File

@ -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,16 +36,15 @@ 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);
@ -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"