mirror of
https://github.com/TriliumNext/Notes.git
synced 2025-07-27 18:12:29 +08:00
Merge pull request #1846 from FliegendeWurst/openapi-revive
OpenAPI documentation fixes
This commit is contained in:
Elian Doran
GitHub
commit
1652481e42
File diff suppressed because one or more lines are too long
@ -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:
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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({
|
||||
|
||||
@ -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> </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> </td><td>The unique ID of a row in <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> </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> </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> </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 <a class="reference-link" href="blobs.md">blobs</a> table.</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td> </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> </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> </td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td> </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> </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> </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> </td><td>The unique ID of a row in <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> </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> </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> </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 <a class="reference-link" href="blobs.md">blobs</a> table.</td></tr><tr><th><code>dateModified</code></th><td>Text</td><td>Non-null</td><td> </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> </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> </td></tr><tr><th><code>isDeleted</code></th><td>Integer</td><td>Non-null</td><td> </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> </td></tr></tbody></table></figure>
|
||||
@ -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",
|
||||
|
||||
@ -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"
|
||||
Loading…
x
Reference in New Issue
Block a user