Add generated openapi docs to website (#1067)

* Add generated openapi docs to website

* Uppercase API link in navbar

* fix(docs): open api empty summary (#1069)

* feat(docs): Use /docs/api path for swagger docs

* Sync api version to be the same as the server

* Update version

Co-authored-by: Jason Rasmussen <jrasm91@gmail.com>
Co-authored-by: Alex Tran <alex.tran1502@gmail.com>

server/apps/immich/src/main.ts

@@ -9,6 +9,7 @@ import { AppModule } from './app.module';
 import { serverVersion } from './constants/server_version.constant';
 import { RedisIoAdapter } from './middlewares/redis-io.adapter.middleware';
 import { json } from 'body-parser';
+import { patchOpenAPI } from './utils/patch-open-api.util';
 
 async function bootstrap() {
   const app = await NestFactory.create<NestExpressApplication>(AppModule);
@@ -26,7 +27,7 @@ async function bootstrap() {
   const config = new DocumentBuilder()
     .setTitle('Immich')
     .setDescription('Immich API')
-    .setVersion('1.17.0')
+    .setVersion(`${serverVersion.major}.${serverVersion.minor}.${serverVersion.patch}`)
     .addBearerAuth({
       type: 'http',
       scheme: 'Bearer',
@@ -55,7 +56,7 @@ async function bootstrap() {
     if (process.env.NODE_ENV == 'development') {
       // Generate API Documentation only in development mode
       const outputPath = path.resolve(process.cwd(), 'immich-openapi-specs.json');
-      writeFileSync(outputPath, JSON.stringify(apiDocument, null, 2), { encoding: 'utf8' });
+      writeFileSync(outputPath, JSON.stringify(patchOpenAPI(apiDocument), null, 2), { encoding: 'utf8' });
       Logger.log(
         `Running Immich Server in DEVELOPMENT environment - version ${serverVersion.major}.${serverVersion.minor}.${serverVersion.patch}`,
         'ImmichServer',

server/apps/immich/src/utils/patch-open-api.util.ts

@@ -0,0 +1,28 @@
+import { OpenAPIObject } from '@nestjs/swagger';
+
+export function patchOpenAPI(document: OpenAPIObject) {
+  for (const path of Object.values(document.paths)) {
+    const operations = {
+      get: path.get,
+      put: path.put,
+      post: path.post,
+      delete: path.delete,
+      options: path.options,
+      head: path.head,
+      patch: path.patch,
+      trace: path.trace,
+    };
+
+    for (const operation of Object.values(operations)) {
+      if (!operation) {
+        continue;
+      }
+
+      if (operation.summary === '') {
+        delete operation.summary;
+      }
+    }
+  }
+
+  return document;
+}

server/immich-openapi-specs.json

@@ -733,7 +733,6 @@
     "/asset": {
       "get": {
         "operationId": "getAllAssets",
-        "summary": "",
         "description": "Get all AssetEntity belong to the user",
         "parameters": [
           {
@@ -850,7 +849,6 @@
     "/asset/{deviceId}": {
       "get": {
         "operationId": "getUserAssetsByDeviceId",
-        "summary": "",
         "description": "Get all asset of a device that are in the database, ID only.",
         "parameters": [
           {
@@ -890,7 +888,6 @@
     "/asset/assetById/{assetId}": {
       "get": {
         "operationId": "getAssetById",
-        "summary": "",
         "description": "Get a single asset's information",
         "parameters": [
           {
@@ -927,7 +924,6 @@
     "/asset/{assetId}": {
       "put": {
         "operationId": "updateAsset",
-        "summary": "",
         "description": "Update an asset",
         "parameters": [
           {
@@ -974,7 +970,6 @@
     "/asset/check": {
       "post": {
         "operationId": "checkDuplicateAsset",
-        "summary": "",
         "description": "Check duplicated asset before uploading - for Web upload used",
         "parameters": [],
         "requestBody": {
@@ -1012,7 +1007,6 @@
     "/asset/exist": {
       "post": {
         "operationId": "checkExistingAssets",
-        "summary": "",
         "description": "Checks if multiple assets exist on the server and returns all existing - used by background backup",
         "parameters": [],
         "requestBody": {
@@ -2108,7 +2102,7 @@
   "info": {
     "title": "Immich",
     "description": "Immich API",
-    "version": "1.17.0",
+    "version": "1.37.0",
     "contact": {}
   },
   "tags": [],