Document sync push/pull

bin/generate-openapi.js

@@ -24,17 +24,48 @@ const options = {
       },
     },
   },
-  apis: ['./src/routes/api/*.ts', './bin/generate-openapi.js'],
+  apis: [
+    // Put individual files here to have them ordered first.
+    './src/routes/api/setup.ts',
+    // all other files
+    './src/routes/api/*.ts', './bin/generate-openapi.js'
+  ],
 };
 
 const openapiSpecification = swaggerJsdoc(options);
 
 console.log(JSON.stringify(openapiSpecification));
 
+/**
+ * @swagger
+ * tags:
+ *   - name: auth
+ *     description: Authentication
+ *   - name: sync
+ *     description: Synchronization
+ */
+
 /**
  * @swagger
  * components:
  *   schemas:
+ *     EntityChange:
+ *       type: object
+ *       properties:
+ *         entityChange:
+ *           type: object
+ *           properties:
+ *             entityName:
+ *               type: string
+ *               example: "notes"
+ *               description: Database table for this entity.
+ *             changeId:
+ *               type: string
+ *               example: "changeId9630"
+ *               description: ID, referenced in `entity_changes` table.
+ *         entity:
+ *           type: object
+ *           description: Encoded entity data. Object has one property for each database column.
  *     UtcDateTime:
  *       type: string
  *       example: "2025-02-13T07:42:47.698Z"

src/routes/api/sync.ts

@@ -86,6 +86,57 @@ function forceFullSync() {
     syncService.sync();
 }
 
+/**
+ * @swagger
+ * /api/sync/changed:
+ *   get:
+ *     summary: Pull sync changes
+ *     operationId: sync-changed
+ *     externalDocs:
+ *       description: Server implementation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/routes/api/sync.ts
+ *     parameters:
+ *       - in: query
+ *         name: instanceId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Local instance ID
+ *       - in: query
+ *         name: lastEntityChangeId
+ *         required: true
+ *         schema:
+ *           type: integer
+ *         description: Last locally present change ID
+ *       - in: query
+ *         name: logMarkerId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Marker to identify this request in server log
+ *     responses:
+ *       '200':
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 entityChanges:
+ *                   type: list
+ *                   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
+ *                   example: 42
+ *                   description: Number of changes not yet returned by the remote.
+ *     security:
+ *       - session: []
+ *     tags:
+ *       - sync
+ */
 function getChanged(req: Request) {
     const startTime = Date.now();
 
@@ -151,6 +202,60 @@ const partialRequests: Record<
     }
 > = {};
 
+/**
+ * @swagger
+ * /api/sync/update:
+ *   put:
+ *     summary: Push sync changes
+ *     description:
+ *       "Basic usage: set `pageCount = 1`, `pageIndex = 0`, and omit `requestId`. Supply your entity changes in the request body."
+ *     operationId: sync-update
+ *     externalDocs:
+ *       description: Server implementation
+ *       url: https://github.com/TriliumNext/Notes/blob/v0.91.6/src/routes/api/sync.ts
+ *     parameters:
+ *       - in: header
+ *         name: pageCount
+ *         required: true
+ *         schema:
+ *           type: integer
+ *       - in: header
+ *         name: pageIndex
+ *         required: true
+ *         schema:
+ *           type: integer
+ *       - in: header
+ *         name: requestId
+ *         schema:
+ *           type: string
+ *           description: ID to identify paginated requests
+ *       - in: query
+ *         name: logMarkerId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Marker to identify this request in server log
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               instanceId:
+ *                 type: string
+ *                 description: Local instance ID
+ *               entities:
+ *                 type: list
+ *                 items:
+ *                   $ref: '#/components/schemas/EntityChange'
+ *     responses:
+ *       '200':
+ *         description: Changes processed successfully
+ *     security:
+ *       - session: []
+ *     tags:
+ *       - sync
+ */
 function update(req: Request) {
     let { body } = req;