feat(@xen-orchestra/rest-api): initial setup for swagger

@xen-orchestra/rest-api/.gitignore

@@ -0,0 +1 @@
+**/open-api/*

@xen-orchestra/rest-api/.npmignore

@@ -0,0 +1 @@
+../../scripts/npmignore

@xen-orchestra/rest-api/eslint.config.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(eslint.configs.recommended, tseslint.configs.recommended)

@xen-orchestra/rest-api/package.json

@@ -0,0 +1,40 @@
+{
+  "author": {
+    "name": "Vates SAS",
+    "url": "https://vates.fr"
+  },
+  "main": "./dist/index.mjs",
+  "name": "@xen-orchestra/rest-api",
+  "homepage": "https://github.com/vatesfr/xen-orchestra/tree/master/@xen-orchestra/rest-api",
+  "version": "0.0.0",
+  "description": "REST API to manage your XOA",
+  "license": "AGPL-3.0-or-later",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20.18"
+  },
+  "scripts": {
+    "build": "tsoa spec-and-routes && tsc",
+    "dev": "tsoa spec-and-routes && tsc --watch",
+    "prepublishOnly": "npm run build",
+    "postversion": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.19.0",
+    "@types/express": "^5.0.0",
+    "@types/swagger-ui-express": "^4.1.7",
+    "typescript": "~5.6.3",
+    "typescript-eslint": "^8.23.0"
+  },
+  "dependencies": {
+    "swagger-ui-express": "^5.0.1",
+    "tsoa": "^6.6.0"
+  },
+  "bugs": "https://github.com/vatesfr/xen-orchestra/issues",
+  "repository": {
+    "directory": "@xen-orchestra/rest-api",
+    "type": "git",
+    "url": "https://github.com/vatesfr/xen-orchestra.git"
+  }
+}

@xen-orchestra/rest-api/src/index.mts

@@ -0,0 +1,18 @@
+import * as swaggerUi from 'swagger-ui-express'
+import { createRequire } from 'module'
+import type { Express } from 'express'
+
+import { RegisterRoutes } from './open-api/routes/routes.js'
+
+// Avoid using "import from" to import a json file as this requires assert/with and will break compatibility with recent node versions
+// https://github.com/nodejs/node/issues/51622
+const require = createRequire(import.meta.url)
+const swaggerOpenApiSpec = require('../open-api/spec/swagger.json')
+
+export default function setupRestApi(express: Express) {
+  RegisterRoutes(express)
+
+  // do not register the doc at the root level, or it may lead to unwated behaviour
+  express.get('/rest/v0', (_req, res) => res.redirect('/rest/v0/docs'))
+  express.use('/rest/v0/docs', swaggerUi.serve, swaggerUi.setup(swaggerOpenApiSpec))
+}

@xen-orchestra/rest-api/src/vms/vm.controller.mts

@@ -0,0 +1,4 @@
+import { Controller, Route } from 'tsoa'
+
+@Route('vms')
+export class VmController extends Controller {}

@xen-orchestra/rest-api/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+
+    "strict": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2023",
+    "skipLibCheck": true,
+
+    /* Experimental options */
+    "experimentalDecorators": true // used by the TSOA framework
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["./node_modules", "./dist"]
+}

@xen-orchestra/rest-api/tsoa.json

@@ -0,0 +1,16 @@
+{
+  "entryFile": "./src/index.mts",
+  "noImplicitAdditionalProperties": "throw-on-extras",
+  "controllerPathGlobs": ["./src/**/*.controller.mts"],
+  "spec": {
+    "outputDirectory": "./open-api/spec",
+    "specVersion": 3,
+    "basePath": "/rest/v0"
+  },
+  "routes": {
+    "routesDir": "./src/open-api/routes",
+    "esm": true,
+    "middleware": "express",
+    "basePath": "/rest/v0"
+  }
+}

CHANGELOG.unreleased.md

@@ -12,6 +12,7 @@
 > Users must be able to say: “Nice enhancement, I'm eager to test it”
 
 - [Plugin/backup-reports] Add VM Description to the backup report. (contribution made by [@truongtx8](https://github.com/truongtx8)) (PR [#8253](https://github.com/vatesfr/xen-orchestra/pull/8253))
+- [REST API] Swagger interface available on `/rest/v0` endpoint. Endpoint documentation will be added step by step (PR [#8316](https://github.com/vatesfr/xen-orchestra/pull/8316))
 
 ### Bug fixes
 
@@ -34,6 +35,7 @@
 <!--packages-start-->
 
 - @vates/types major
+- @xen-orchestra/rest-api minor
 - @xen-orchestra/web-core minor
 - xo-server-auth-oidc patch
 - xo-server-backup-reports minor

packages/xo-server/package.json

@@ -54,6 +54,7 @@
     "@xen-orchestra/log": "^0.7.1",
     "@xen-orchestra/mixin": "^0.2.0",
     "@xen-orchestra/mixins": "^0.16.2",
+    "@xen-orchestra/rest-api": "^0.0.0",
     "@xen-orchestra/self-signed": "^0.2.1",
     "@xen-orchestra/template": "^0.1.0",
     "@xen-orchestra/vmware-explorer": "^0.9.0",

packages/xo-server/src/xo-mixins/rest-api.mjs

@@ -1,3 +1,4 @@
+import setupRestApi from '@xen-orchestra/rest-api'
 import { asyncEach } from '@vates/async-each'
 import { createGzip } from 'node:zlib'
 import { defer } from 'golike-defer'
@@ -1139,11 +1140,6 @@ export default class RestApi {
       }
     })
 
-    api.get(
-      '/',
-      wrap((req, res) => sendObjects(Object.values(collections), req, res))
-    )
-
     // For compatibility redirect from /backups* to /backup
     api.get('/backups*', (req, res) => {
       res.redirect(308, req.baseUrl + '/backup' + req.params[0])
@@ -1514,6 +1510,8 @@ export default class RestApi {
         res.sendStatus(200)
       })
     )
+
+    setupRestApi(express)
   }
 
   registerRestApi(spec, base = '/') {

scripts/npmignore

@@ -33,3 +33,4 @@ __snapshots__/
 
 /docs/
 /src/
+eslint.config.mjs