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>

docs/docusaurus.config.js

@@ -30,8 +30,8 @@ const config = {
 
   presets: [
     [
-      "classic",
+      "docusaurus-preset-openapi",
-      /** @type {import('@docusaurus/preset-classic').Options} */
+      /** @type {import('docusaurus-preset-openapi').Options} */
       ({
         docs: {
           showLastUpdateAuthor: true,
@@ -42,6 +42,10 @@ const config = {
           // Remove this to remove the "edit this page" links.
           editUrl: "https://github.com/immich-app/immich/tree/main/docs/",
         },
+        api: {
+          path: "../server/immich-openapi-specs.json",
+          routeBasePath: "/docs/api"
+        },
         // blog: {
         //   showReadingTime: true,
         //   editUrl: "https://github.com/immich-app/immich/tree/main/docs/",
@@ -80,6 +84,11 @@ const config = {
             position: "right",
             label: "Documentation",
           },
+          {
+            to: "/docs/api",
+            position: "right",
+            label: "API"
+          },
           { to: "/blog", label: "Blog", position: "right" },
           {
             href: "https://github.com/immich-app/immich",

docs/package.json

@@ -19,9 +19,11 @@
     "@docusaurus/preset-classic": "2.1.0",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
+    "docusaurus-preset-openapi": "^0.6.3",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react-dom": "^17.0.2",
+    "url": "^0.11.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.1.0",

mobile/openapi/lib/api/asset_api.dart

@@ -16,8 +16,6 @@ class AssetApi {
 
   final ApiClient apiClient;
 
-  /// 
-  ///
   /// Check duplicated asset before uploading - for Web upload used
   ///
   /// Note: This method returns the HTTP [Response].
@@ -50,8 +48,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Check duplicated asset before uploading - for Web upload used
   ///
   /// Parameters:
@@ -72,8 +68,6 @@ class AssetApi {
     return null;
   }
 
-  /// 
-  ///
   /// Checks if multiple assets exist on the server and returns all existing - used by background backup
   ///
   /// Note: This method returns the HTTP [Response].
@@ -106,8 +100,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Checks if multiple assets exist on the server and returns all existing - used by background backup
   ///
   /// Parameters:
@@ -292,8 +284,6 @@ class AssetApi {
     return null;
   }
 
-  /// 
-  ///
   /// Get all AssetEntity belong to the user
   ///
   /// Note: This method returns the HTTP [Response].
@@ -331,8 +321,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Get all AssetEntity belong to the user
   ///
   /// Parameters:
@@ -357,8 +345,6 @@ class AssetApi {
     return null;
   }
 
-  /// 
-  ///
   /// Get a single asset's information
   ///
   /// Note: This method returns the HTTP [Response].
@@ -392,8 +378,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Get a single asset's information
   ///
   /// Parameters:
@@ -740,8 +724,6 @@ class AssetApi {
     return null;
   }
 
-  /// 
-  ///
   /// Get all asset of a device that are in the database, ID only.
   ///
   /// Note: This method returns the HTTP [Response].
@@ -775,8 +757,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Get all asset of a device that are in the database, ID only.
   ///
   /// Parameters:
@@ -913,8 +893,6 @@ class AssetApi {
     return null;
   }
 
-  /// 
-  ///
   /// Update an asset
   ///
   /// Note: This method returns the HTTP [Response].
@@ -950,8 +928,6 @@ class AssetApi {
     );
   }
 
-  /// 
-  ///
   /// Update an asset
   ///
   /// Parameters:

mobile/openapi/test/asset_api_test.dart

@@ -17,8 +17,6 @@ void main() {
   // final instance = AssetApi();
 
   group('tests for AssetApi', () {
-    // 
-    //
     // Check duplicated asset before uploading - for Web upload used
     //
     //Future<CheckDuplicateAssetResponseDto> checkDuplicateAsset(CheckDuplicateAssetDto checkDuplicateAssetDto) async
@@ -26,8 +24,6 @@ void main() {
       // TODO
     });
 
-    // 
-    //
     // Checks if multiple assets exist on the server and returns all existing - used by background backup
     //
     //Future<CheckExistingAssetsResponseDto> checkExistingAssets(CheckExistingAssetsDto checkExistingAssetsDto) async
@@ -50,8 +46,6 @@ void main() {
       // TODO
     });
 
-    // 
-    //
     // Get all AssetEntity belong to the user
     //
     //Future<List<AssetResponseDto>> getAllAssets({ String ifNoneMatch }) async
@@ -59,8 +53,6 @@ void main() {
       // TODO
     });
 
-    // 
-    //
     // Get a single asset's information
     //
     //Future<AssetResponseDto> getAssetById(String assetId) async
@@ -103,8 +95,6 @@ void main() {
       // TODO
     });
 
-    // 
-    //
     // Get all asset of a device that are in the database, ID only.
     //
     //Future<List<String>> getUserAssetsByDeviceId(String deviceId) async
@@ -122,8 +112,6 @@ void main() {
       // TODO
     });
 
-    // 
-    //
     // Update an asset
     //
     //Future<AssetResponseDto> updateAsset(String assetId, UpdateAssetDto updateAssetDto) async

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": [],

web/src/api/open-api/api.ts

@@ -2685,7 +2685,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
     return {
         /**
          * Check duplicated asset before uploading - for Web upload used
-         * @summary 
          * @param {CheckDuplicateAssetDto} checkDuplicateAssetDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -2725,7 +2724,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
         },
         /**
          * Checks if multiple assets exist on the server and returns all existing - used by background backup
-         * @summary 
          * @param {CheckExistingAssetsDto} checkExistingAssetsDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -2889,7 +2887,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
         },
         /**
          * Get all AssetEntity belong to the user
-         * @summary 
          * @param {string} [ifNoneMatch] ETag of data already cached on the client
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -2928,7 +2925,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
         },
         /**
          * Get a single asset\'s information
-         * @summary 
          * @param {string} assetId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3218,7 +3214,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
         },
         /**
          * Get all asset of a device that are in the database, ID only.
-         * @summary 
          * @param {string} deviceId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3342,7 +3337,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
         },
         /**
          * Update an asset
-         * @summary 
          * @param {string} assetId 
          * @param {UpdateAssetDto} updateAssetDto 
          * @param {*} [options] Override http request option.
@@ -3440,7 +3434,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
     return {
         /**
          * Check duplicated asset before uploading - for Web upload used
-         * @summary 
          * @param {CheckDuplicateAssetDto} checkDuplicateAssetDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3451,7 +3444,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
         },
         /**
          * Checks if multiple assets exist on the server and returns all existing - used by background backup
-         * @summary 
          * @param {CheckExistingAssetsDto} checkExistingAssetsDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3494,7 +3486,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
         },
         /**
          * Get all AssetEntity belong to the user
-         * @summary 
          * @param {string} [ifNoneMatch] ETag of data already cached on the client
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3505,7 +3496,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
         },
         /**
          * Get a single asset\'s information
-         * @summary 
          * @param {string} assetId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3583,7 +3573,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
         },
         /**
          * Get all asset of a device that are in the database, ID only.
-         * @summary 
          * @param {string} deviceId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3616,7 +3605,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
         },
         /**
          * Update an asset
-         * @summary 
          * @param {string} assetId 
          * @param {UpdateAssetDto} updateAssetDto 
          * @param {*} [options] Override http request option.
@@ -3648,7 +3636,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
     return {
         /**
          * Check duplicated asset before uploading - for Web upload used
-         * @summary 
          * @param {CheckDuplicateAssetDto} checkDuplicateAssetDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3658,7 +3645,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
         },
         /**
          * Checks if multiple assets exist on the server and returns all existing - used by background backup
-         * @summary 
          * @param {CheckExistingAssetsDto} checkExistingAssetsDto 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3697,7 +3683,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
         },
         /**
          * Get all AssetEntity belong to the user
-         * @summary 
          * @param {string} [ifNoneMatch] ETag of data already cached on the client
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3707,7 +3692,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
         },
         /**
          * Get a single asset\'s information
-         * @summary 
          * @param {string} assetId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3777,7 +3761,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
         },
         /**
          * Get all asset of a device that are in the database, ID only.
-         * @summary 
          * @param {string} deviceId 
          * @param {*} [options] Override http request option.
          * @throws {RequiredError}
@@ -3807,7 +3790,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
         },
         /**
          * Update an asset
-         * @summary 
          * @param {string} assetId 
          * @param {UpdateAssetDto} updateAssetDto 
          * @param {*} [options] Override http request option.
@@ -3837,7 +3819,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
 export class AssetApi extends BaseAPI {
     /**
      * Check duplicated asset before uploading - for Web upload used
-     * @summary 
      * @param {CheckDuplicateAssetDto} checkDuplicateAssetDto 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
@@ -3849,7 +3830,6 @@ export class AssetApi extends BaseAPI {
 
     /**
      * Checks if multiple assets exist on the server and returns all existing - used by background backup
-     * @summary 
      * @param {CheckExistingAssetsDto} checkExistingAssetsDto 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
@@ -3896,7 +3876,6 @@ export class AssetApi extends BaseAPI {
 
     /**
      * Get all AssetEntity belong to the user
-     * @summary 
      * @param {string} [ifNoneMatch] ETag of data already cached on the client
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
@@ -3908,7 +3887,6 @@ export class AssetApi extends BaseAPI {
 
     /**
      * Get a single asset\'s information
-     * @summary 
      * @param {string} assetId 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
@@ -3994,7 +3972,6 @@ export class AssetApi extends BaseAPI {
 
     /**
      * Get all asset of a device that are in the database, ID only.
-     * @summary 
      * @param {string} deviceId 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
@@ -4030,7 +4007,6 @@ export class AssetApi extends BaseAPI {
 
     /**
      * Update an asset
-     * @summary 
      * @param {string} assetId 
      * @param {UpdateAssetDto} updateAssetDto 
      * @param {*} [options] Override http request option.