docs: Upgrade internal API docs to use OpenAPI 3.x

Implements #511
ptarmiganlabs · Jun 22, 2022 · c444943 · c444943
1 parent 2e4b00e
commit c444943
Show file tree

Hide file tree

Showing 13 changed files with 259 additions and 251 deletions.
diff --git a/src/api/api.js b/src/api/api.js
@@ -10,7 +10,7 @@ const apiGetAPIEndpointsEnabled = {
                 items: {
                     type: 'string',
                 },
-                example: ['activeUserCount', 'activeUsers', 'apiListEnbledEndpoints'],
+                examples: [['activeUserCount', 'activeUsers', 'apiListEnbledEndpoints']],
             },
         },
     },

diff --git a/src/api/base_conversion.js b/src/api/base_conversion.js
@@ -8,7 +8,7 @@ const apiGetBase62ToBase16 = {
                 base62: {
                     type: 'string',
                     description: 'The base62 encoded string that should be converted to base16',
-                    example: '6DMW88LpSok9Z7P7hUK0wv7bF',
+                    examples: ['6DMW88LpSok9Z7P7hUK0wv7bF'],
                 },
             },
             required: ['base62'],
@@ -27,10 +27,7 @@ const apiGetBase62ToBase16 = {
                         description: 'Resulting base16 encoded string.',
                     },
                 },
-                example: {
-                    base62: '6DMW88LpSok9Z7P7hUK0wv7bF',
-                    base16: '3199af08bfeeaf5d420f27ed9c01e74370077',
-                },
+                examples: [{ base62: '6DMW88LpSok9Z7P7hUK0wv7bF', base16: '3199af08bfeeaf5d420f27ed9c01e74370077' }],
             },
             400: {
                 description: 'Required parameter missing.',
@@ -68,7 +65,7 @@ const apiGetBase16ToBase62 = {
                 base16: {
                     type: 'string',
                     description: 'The base16 encoded string that should be converted to base62',
-                    example: '3199af08bfeeaf5d420f27ed9c01e74370077',
+                    examples: ['3199af08bfeeaf5d420f27ed9c01e74370077'],
                 },
             },
             required: ['base16'],
@@ -87,10 +84,12 @@ const apiGetBase16ToBase62 = {
                         description: 'Resulting base62 encoded string.',
                     },
                 },
-                example: {
-                    base16: '3199af08bfeeaf5d420f27ed9c01e74370077',
-                    base62: '6DMW88LpSok9Z7P7hUK0wv7bF',
-                },
+                examples: [
+                    {
+                        base16: '3199af08bfeeaf5d420f27ed9c01e74370077',
+                        base62: '6DMW88LpSok9Z7P7hUK0wv7bF',
+                    },
+                ],
             },
             400: {
                 description: 'Required parameter missing.',

diff --git a/src/api/disk_utils.js b/src/api/disk_utils.js
@@ -9,24 +9,24 @@ const apiFileCopy = {
                 fromFile: {
                     type: 'string',
                     description: 'Name of source file.',
-                    example: 'subfolder/file1.qvd',
+                    examples: ['subfolder/file1.qvd'],
                 },
                 toFile: {
                     type: 'string',
                     description: 'Name of destination file. Can be different from source file name, if needed.',
-                    example: 'archive/file1_20200925.qvd',
+                    examples: ['archive/file1_20200925.qvd'],
                 },
                 overwrite: {
                     type: 'boolean',
                     description:
                         'Controls whether destination file should be overwritten if it already exists. Note that the copy operation will silently fail if you set this to false and the destination exists. Defaults to false.',
-                    example: false,
+                    examples: [false],
                 },
                 preserveTimestamp: {
                     type: 'boolean',
                     description:
                         'When true, the timestamp of the source file(s) will be preserved on the destination file(s). When false, timestamp behaviour is OS-dependent. Defaults to false.',
-                    example: false,
+                    examples: [false],
                 },
             },
         },
@@ -38,24 +38,24 @@ const apiFileCopy = {
                     fromFile: {
                         type: 'string',
                         description: 'Name of source file.',
-                        example: 'subfolder/file1.qvd',
+                        examples: ['subfolder/file1.qvd'],
                     },
                     toFile: {
                         type: 'string',
                         description: 'Name of destination file. Can be different from source file name, if needed.',
-                        example: 'archive/file1_20200925.qvd',
+                        examples: ['archive/file1_20200925.qvd'],
                     },
                     overwrite: {
                         type: 'boolean',
                         description:
                             'Controls whether destination file should be overwritten if it already exists. Note that the copy operation will silently fail if you set this to false and the destination exists. Defaults to false.',
-                        example: false,
+                        examples: [false],
                     },
                     preserveTimestamp: {
                         type: 'boolean',
                         description:
                             'When true, the timestamp of the source file(s) will be preserved on the destination file(s). When false, timestamp behaviour is OS-dependent. Defaults to false.',
-                        example: false,
+                        examples: [false],
                     },
                 },
             },
@@ -107,17 +107,17 @@ const apiFileMove = {
                 fromFile: {
                     type: 'string',
                     description: 'Name of source file.',
-                    example: 'subfolder/file1.qvd',
+                    examples: ['subfolder/file1.qvd'],
                 },
                 toFile: {
                     type: 'string',
                     description: 'Name of destination file. Can be different from source file name, if needed.',
-                    example: 'archive/file1_20200925.qvd',
+                    examples: ['archive/file1_20200925.qvd'],
                 },
                 overwrite: {
                     type: 'boolean',
                     description: 'Controls whether destination file should be overwritten if it already exists. Defaults to false.',
-                    example: false,
+                    examples: [false],
                 },
             },
         },
@@ -129,17 +129,17 @@ const apiFileMove = {
                     fromFile: {
                         type: 'string',
                         description: 'Name of source file.',
-                        example: 'subfolder/file1.qvd',
+                        examples: ['subfolder/file1.qvd'],
                     },
                     toFile: {
                         type: 'string',
                         description: 'Name of destination file. Can be different from source file name, if needed.',
-                        example: 'archive/file1_20200925.qvd',
+                        examples: ['archive/file1_20200925.qvd'],
                     },
                     overwrite: {
                         type: 'boolean',
                         description: 'Controls whether destination file should be overwritten if it already exists. Defaults to false.',
-                        example: false,
+                        examples: [false],
                     },
                 },
             },
@@ -192,7 +192,7 @@ const apiFileDelete = {
                     type: 'string',
                     description:
                         'Name of file to be deleted. Use forward/backward slashes in paths as needed, depending on whether Butler runs on Windows/non-Windows platform.',
-                    example: 'data/qvdstore/sales/file1.qvd',
+                    examples: ['data/qvdstore/sales/file1.qvd'],
                 },
             },
         },
@@ -249,7 +249,7 @@ const apiCreateDir = {
                 directory: {
                     type: 'string',
                     description: 'Path to directory that should be created. Can be a relative or absolute path.',
-                    example: '/Users/joe/data/qvds/2020',
+                    examples: ['/Users/joe/data/qvds/2020'],
                 },
             },
         },
@@ -261,7 +261,7 @@ const apiCreateDir = {
                     directory: {
                         type: 'string',
                         description: 'Directory that was created.',
-                        example: '/Users/joe/data/qvds/2020',
+                        examples: ['/Users/joe/data/qvds/2020'],
                     },
                 },
             },
@@ -301,7 +301,7 @@ const apiCreateDirQvd = {
                 directory: {
                     type: 'string',
                     description: 'Directory that should be created.',
-                    example: 'subfolder/2020-10',
+                    examples: ['subfolder/2020-10'],
                 },
             },
         },
@@ -313,7 +313,7 @@ const apiCreateDirQvd = {
                     directory: {
                         type: 'string',
                         description: 'Directory that was created.',
-                        example: 'subfolder/2020-10',
+                        examples: ['subfolder/2020-10'],
                     },
                 },
             },