Merge pull request #1179 from FliegendeWurst/openapi-docs

Automated OpenAPI spec generation

src/routes/api/app_info.ts

@@ -2,6 +2,51 @@
 
 import appInfo from "../../services/app_info.js";
 
+/**
+ * @swagger
+ * /api/app-info:
+ *   get:
+ *     summary: Get installation info
+ *     operationId: app-info
+ *     externalDocs:
+ *       description: Server implementation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/services/app_info.ts
+ *     responses:
+ *       '200':
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 appVersion:
+ *                   type: string
+ *                   example: "0.91.6"
+ *                 dbVersion:
+ *                   type: integer
+ *                   example: 228
+ *                 nodeVersion:
+ *                   type: string
+ *                   description: "value of process.version"
+ *                 syncVersion:
+ *                   type: integer
+ *                   example: 34
+ *                 buildDate:
+ *                   type: string
+ *                   example: "2024-09-07T18:36:34Z"
+ *                 buildRevision:
+ *                   type: string
+ *                   example: "7c0d6930fa8f20d269dcfbcbc8f636a25f6bb9a7"
+ *                 dataDirectory:
+ *                   type: string
+ *                   example: "/var/lib/trilium"
+ *                 clipperProtocolVersion:
+ *                   type: string
+ *                   example: "1.0"
+ *                 utcDateTime:
+ *                   $ref: '#/components/schemas/UtcDateTime'
+ *     security:
+ *       - session: []
+ */
 function getAppInfo() {
     return appInfo;
 }

src/routes/api/login.ts

@@ -14,6 +14,68 @@ import ws from "../../services/ws.js";
 import etapiTokenService from "../../services/etapi_tokens.js";
 import type { Request } from "express";
 
+/**
+ * @swagger
+ * /api/login/sync:
+ *   post:
+ *     tags:
+ *       - auth
+ *     summary: Log in using documentSecret
+ *     description: The `hash` parameter is computed using a HMAC of the `documentSecret` and `timestamp`.
+ *     operationId: login-sync
+ *     externalDocs:
+ *       description: HMAC calculation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/services/utils.ts#L62-L66
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               timestamp:
+ *                 $ref: '#/components/schemas/UtcDateTime'
+ *               hash:
+ *                 type: string
+ *               syncVersion:
+ *                 type: integer
+ *                 example: 34
+ *     responses:
+ *       '200':
+ *         description: Successful operation
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 syncVersion:
+ *                   type: integer
+ *                   example: 34
+ *                 options:
+ *                   type: object
+ *                   properties:
+ *                     documentSecret:
+ *                       type: string
+ *       '400':
+ *         description: Sync version / document secret mismatch
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: "Non-matching sync versions, local is version ${server syncVersion}, remote is ${requested syncVersion}. It is recommended to run same version of Trilium on both sides of sync"
+ *       '401':
+ *         description: Timestamp mismatch
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: "Auth request time is out of sync, please check that both client and server have correct time. The difference between clocks has to be smaller than 5 minutes"
+ */
 function loginSync(req: Request) {
     if (!sqlInit.schemaExists()) {
         return [500, { message: "DB schema does not exist, can't sync." }];

src/routes/api/setup.ts

@@ -45,6 +45,34 @@ function saveSyncSeed(req: Request) {
     sqlInit.createDatabaseForSync(options);
 }
 
+/**
+ * @swagger
+ * /api/setup/sync-seed:
+ *   get:
+ *     tags:
+ *       - auth
+ *     summary: Sync documentSecret value
+ *     description: First step to logging in.
+ *     operationId: setup-sync-seed
+ *     responses:
+ *       '200':
+ *         description: Successful operation
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 syncVersion:
+ *                   type: integer
+ *                   example: 34
+ *                 options:
+ *                   type: object
+ *                   properties:
+ *                     documentSecret:
+ *                       type: string
+ *     security:
+ *       - user-password: []
+ */
 function getSyncSeed() {
     log.info("Serving sync seed.");