Feat/restructure api (#6664)

* Restructured rest api

* Added swagger ui

* Added reworked rest api

* Reformatted code, excluded unnecessary newlines and removed version 2.2.2

bin/make_docs.ts

@@ -57,7 +57,7 @@ createDirIfNotExists('../out/doc/api')
 
 
 
-exec(`asciidoctor -D ../out/doc ../doc/index.adoc */**.adoc -a VERSION=${VERSION}`)
+exec(`asciidoctor -D ../out/doc ../doc/index.adoc ../*/**.adoc -a VERSION=${VERSION}`)
 exec(`asciidoctor -D ../out/doc/api  ../doc/api/*.adoc -a VERSION=${VERSION}`)
 
 copyFolderSync('../doc/public/', '../out/doc/')

pnpm-lock.yaml

@@ -257,6 +257,9 @@ importers:
       superagent:
         specifier: 10.1.0
         version: 10.1.0
+      swagger-ui-express:
+        specifier: ^5.0.1
+        version: 5.0.1(express@4.21.0)
       tinycon:
         specifier: 0.6.8
         version: 0.6.8
@@ -324,6 +327,9 @@ importers:
       '@types/supertest':
         specifier: ^6.0.2
         version: 6.0.2
+      '@types/swagger-ui-express':
+        specifier: ^4.1.6
+        version: 4.1.6
       '@types/underscore':
         specifier: ^1.11.15
         version: 1.11.15
@@ -1618,6 +1624,9 @@ packages:
   '@types/supertest@6.0.2':
     resolution: {integrity: sha512-137ypx2lk/wTQbW6An6safu9hXmajAifU/s7szAHLN/FeIm5w7yR0Wkl9fdJMRSHwOn4HLAI0DaB2TOORuhPDg==}
 
+  '@types/swagger-ui-express@4.1.6':
+    resolution: {integrity: sha512-UVSiGYXa5IzdJJG3hrc86e8KdZWLYxyEsVoUI4iPXc7CO4VZ3AfNP8d/8+hrDRIqz+HAaSMtZSqAsF3Nq2X/Dg==}
+
   '@types/tar@6.1.13':
     resolution: {integrity: sha512-IznnlmU5f4WcGTh2ltRu/Ijpmk8wiWXfF0VA4s+HPjHZgvFggk1YaIkbo5krX/zUCzWF8N/l4+W/LNxnvAJ8nw==}
 
@@ -4266,6 +4275,15 @@ packages:
   swagger-schema-official@2.0.0-bab6bed:
     resolution: {integrity: sha512-rCC0NWGKr/IJhtRuPq/t37qvZHI/mH4I4sxflVM+qgVe5Z2uOCivzWaVbuioJaB61kvm5UvB7b49E+oBY0M8jA==}
 
+  swagger-ui-dist@5.17.14:
+    resolution: {integrity: sha512-CVbSfaLpstV65OnSjbXfVd6Sta3q3F7Cj/yYuvHMp1P90LztOLs6PfUnKEVAeiIVQt9u2SaPwv0LiH/OyMjHRw==}
+
+  swagger-ui-express@5.0.1:
+    resolution: {integrity: sha512-SrNU3RiBGTLLmFU8GIJdOdanJTl4TOmT27tt3bWWHppqYmAZ6IDuEuBvMU6nZq0zLEe6b/1rACXCgLZqO6ZfrA==}
+    engines: {node: '>= v0.10.32'}
+    peerDependencies:
+      express: '>=4.0.0 || >=5.0.0-beta'
+
   symbol-tree@3.2.4:
     resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
 
@@ -5900,6 +5918,11 @@ snapshots:
       '@types/methods': 1.1.4
       '@types/superagent': 8.1.7
 
+  '@types/swagger-ui-express@4.1.6':
+    dependencies:
+      '@types/express': 4.17.21
+      '@types/serve-static': 1.15.7
+
   '@types/tar@6.1.13':
     dependencies:
       '@types/node': 22.5.5
@@ -9017,6 +9040,13 @@ snapshots:
 
   swagger-schema-official@2.0.0-bab6bed: {}
 
+  swagger-ui-dist@5.17.14: {}
+
+  swagger-ui-express@5.0.1(express@4.21.0):
+    dependencies:
+      express: 4.21.0
+      swagger-ui-dist: 5.17.14
+
   symbol-tree@3.2.4: {}
 
   tabbable@6.2.0: {}

src/ep.json

@@ -82,6 +82,12 @@
         "expressCreateServer": "ep_etherpad-lite/node/hooks/express/errorhandling"
       }
     },
+    {
+      "name": "restApi",
+      "hooks": {
+        "expressCreateServer": "ep_etherpad-lite/node/handler/RestAPI"
+      }
+    },
     {
       "name": "socketio",
       "hooks": {

src/node/handler/APIHandler.ts

@@ -24,10 +24,10 @@ import {MapArrayType} from "../types/MapType";
 const api = require('../db/API');
 const padManager = require('../db/PadManager');
 import createHTTPError from 'http-errors';
-import {Http2ServerRequest, Http2ServerResponse} from "node:http2";
+import {Http2ServerRequest} from "node:http2";
 import {publicKeyExported} from "../security/OAuth2Provider";
 import {jwtVerify} from "jose";
-import {apikey} from './APIKeyHandler'
+import {APIFields, apikey} from './APIKeyHandler'
 // a list of all functions
 const version:MapArrayType<any> = {};
 
@@ -141,6 +141,7 @@ version['1.3.0'] = {
   setText: ['padID', 'text', 'authorId'],
 };
 
+
 // set the latest available API version here
 exports.latestApiVersion = '1.3.0';
 
@@ -148,13 +149,6 @@ exports.latestApiVersion = '1.3.0';
 exports.version = version;
 
 
-type APIFields = {
-  apikey: string;
-  api_key: string;
-  padID: string;
-  padName: string;
-  authorization: string;
-}
 
 /**
  * Handles an HTTP API call

src/node/handler/APIKeyHandler.ts

@@ -7,6 +7,16 @@ const settings = require('../utils/Settings');
 
 const apiHandlerLogger = log4js.getLogger('APIHandler');
 
+
+
+export type APIFields = {
+  apikey: string;
+  api_key: string;
+  padID: string;
+  padName: string;
+  authorization: string;
+}
+
 // ensure we have an apikey
 export let apikey:string|null = null;
 const apikeyFilename = absolutePaths.makeAbsolute(argv.apikey || './APIKEY.txt');

src/node/hooks/express/specialpages.ts

@@ -12,6 +12,7 @@ const webaccess = require('./webaccess');
 const plugins = require('../../../static/js/pluginfw/plugin_defs');
 
 import {build, buildSync} from 'esbuild'
+import {ArgsExpressType} from "../../types/ArgsExpressType";
 let ioI: { sockets: { sockets: any[]; }; } | null = null
 
 exports.socketio = (hookName: string, {io}: any) => {
@@ -19,7 +20,7 @@ exports.socketio = (hookName: string, {io}: any) => {
 }
 
 
-exports.expressPreSession = async (hookName:string, {app}:any) => {
+exports.expressPreSession = async (hookName:string, {app}:ArgsExpressType) => {
   // This endpoint is intended to conform to:
   // https://www.ietf.org/archive/id/draft-inadarei-api-health-check-06.html
   app.get('/health', (req:any, res:any) => {
@@ -243,7 +244,7 @@ const convertTypescriptWatched = (content: string, cb: (output:string, hash: str
   })
 }
 
-exports.expressCreateServer = async (hookName: string, args: any, cb: Function) => {
+exports.expressCreateServer = async (hookName: string, args: ArgsExpressType, cb: Function) => {
   const padString =   eejs.require('ep_etherpad-lite/templates/padBootstrap.js', {
       pluginModules: (() => {
         const pluginModules = new Set();

src/node/security/OAuth2Provider.ts

@@ -153,7 +153,7 @@ export const expressCreateServer = async (hookName: string, args: ArgsExpressTyp
     });
 
 
-    args.app.post('/interaction/:uid', async (req: Http2ServerRequest, res: Http2ServerResponse, next:Function) => {
+    args.app.post('/interaction/:uid', async (req, res, next) => {
         const formid = new IncomingForm();
         try {
             // @ts-ignore
@@ -226,7 +226,7 @@ export const expressCreateServer = async (hookName: string, args: ArgsExpressTyp
     })
 
 
-    args.app.get('/interaction/:uid', async (req: Request, res: Response, next: Function) => {
+    args.app.get('/interaction/:uid', async (req, res, next) => {
         try {
             const {
                 uid, prompt, params, session,

src/node/types/ArgsExpressType.ts

@@ -1,5 +1,7 @@
+import {Express} from "express";
+
 export type ArgsExpressType = {
-    app:any,
+    app:Express,
     io: any,
     server:any
 }

src/package.json

@@ -69,6 +69,7 @@
     "socket.io": "^4.7.5",
     "socket.io-client": "^4.7.5",
     "superagent": "10.1.0",
+    "swagger-ui-express": "^5.0.1",
     "tinycon": "0.6.8",
     "tsx": "4.19.1",
     "ueberdb2": "^5.0.2",
@@ -97,6 +98,7 @@
     "@types/semver": "^7.5.8",
     "@types/sinon": "^17.0.3",
     "@types/supertest": "^6.0.2",
+    "@types/swagger-ui-express": "^4.1.6",
     "@types/underscore": "^1.11.15",
     "@types/whatwg-mimetype": "^3.0.2",
     "chokidar": "^4.0.0",