chore: document endpoint tagged Unstable

src/lib/features/export-import-toggles/export-import-controller.ts

@@ -16,13 +16,15 @@ import {
     emptyResponse,
     ExportQuerySchema,
     exportResultSchema,
+    getStandardResponses,
     ImportTogglesSchema,
     importTogglesValidateSchema,
 } from '../../openapi';
 import { IAuthRequest } from '../../routes/unleash-types';
 import { extractUsername } from '../../util';
 import { BadDataError, InvalidOperationError } from '../../error';
 import ApiUser from '../../types/api-user';
+import { endpointDescriptions } from '../../openapi/endpoint-descriptions';
 
 class ExportImportController extends Controller {
     private logger: Logger;
@@ -65,12 +67,14 @@ class ExportImportController extends Controller {
             handler: this.export,
             middleware: [
                 this.openApiService.validPath({
-                    tags: ['Unstable'],
+                    tags: ['Import/Export'],
                     operationId: 'exportFeatures',
                     requestBody: createRequestSchema('exportQuerySchema'),
                     responses: {
                         200: createResponseSchema('exportResultSchema'),
+                        ...getStandardResponses(404),
                     },
+                    ...endpointDescriptions.admin.export,
                 }),
             ],
         });
@@ -81,17 +85,16 @@ class ExportImportController extends Controller {
             handler: this.validateImport,
             middleware: [
                 openApiService.validPath({
-                    summary:
-                        'Validate import of feature toggles for an environment in the project',
-                    description: `Unleash toggles exported from a different instance can be imported into a new project and environment`,
-                    tags: ['Unstable'],
+                    tags: ['Import/Export'],
                     operationId: 'validateImport',
                     requestBody: createRequestSchema('importTogglesSchema'),
                     responses: {
                         200: createResponseSchema(
                             'importTogglesValidateSchema',
                         ),
+                        ...getStandardResponses(404),
                     },
+                    ...endpointDescriptions.admin.validateImport,
                 }),
             ],
         });
@@ -102,15 +105,14 @@ class ExportImportController extends Controller {
             handler: this.importData,
             middleware: [
                 openApiService.validPath({
-                    summary:
-                        'Import feature toggles for an environment in the project',
-                    description: `Unleash toggles exported from a different instance can be imported into a new project and environment`,
-                    tags: ['Unstable'],
+                    tags: ['Import/Export'],
                     operationId: 'importToggles',
                     requestBody: createRequestSchema('importTogglesSchema'),
                     responses: {
                         200: emptyResponse,
+                        ...getStandardResponses(404),
                     },
+                    ...endpointDescriptions.admin.import,
                 }),
             ],
         });

src/lib/openapi/endpoint-descriptions.ts

@@ -23,5 +23,18 @@ export const endpointDescriptions = {
             summary:
                 'Batch evaluate an Unleash context against a set of environments and projects.',
         },
+        export: {
+            description:
+                "Exports all features listed in the `features` property from the environment specified in the request body. If set to `true`, the `downloadFile` property will let you download a file with the exported data. Otherwise, the export data is returned directly as JSON. Refer to the documentation for more information about [Unleash's export functionality](https://docs.getunleash.io/reference/deploy/environment-import-export#export).",
+            summary: 'Export feature toggles from an environment',
+        },
+        validateImport: {
+            summary: 'Validate feature import data',
+            description: `Validates a feature toggle data set. Checks whether the data can be imported into the specified project and environment. The returned value is an object that contains errors, warnings, and permissions required to perform the import, as described in the [import documentation](https://docs.getunleash.io/reference/deploy/environment-import-export#import).`,
+        },
+        import: {
+            summary: 'Import feature toggles',
+            description: `[Import feature toggles](https://docs.getunleash.io/reference/deploy/environment-import-export#import) into a specific project and environment.`,
+        },
     },
 } as const;

src/lib/openapi/spec/export-query-schema.ts

@@ -8,9 +8,13 @@ export const exportQuerySchema = {
     properties: {
         environment: {
             type: 'string',
+            example: 'development',
+            description: 'The environment to export from',
         },
         downloadFile: {
             type: 'boolean',
+            example: 'development',
+            description: 'Whether to return a downloadable file',
         },
     },
     oneOf: [
@@ -19,6 +23,7 @@ export const exportQuerySchema = {
             properties: {
                 features: {
                     type: 'array',
+                    example: ['MyAwesomeFeature'],
                     items: {
                         type: 'string',
                         minLength: 1,
@@ -32,6 +37,7 @@ export const exportQuerySchema = {
             properties: {
                 tag: {
                     type: 'string',
+                    example: 'release',
                     description:
                         'Selects features to export by tag. Takes precedence over the features field.',
                 },

src/lib/openapi/spec/export-result-schema.ts

@@ -16,6 +16,9 @@ export const exportResultSchema = {
     $id: '#/components/schemas/exportResultSchema',
     type: 'object',
     additionalProperties: false,
+    description:
+        'The result of the export operation, providing you with the feature toggle definitions, strategy definitions and the rest of the elements relevant to the features (tags, environments etc.)',
+    summary: 'The export result schema',
     required: ['features', 'featureStrategies', 'tagTypes'],
     properties: {
         features: {

src/lib/openapi/spec/import-toggles-schema.ts

@@ -19,12 +19,21 @@ export const importTogglesSchema = {
     type: 'object',
     required: ['project', 'environment', 'data'],
     additionalProperties: false,
+    summary: 'Import toggles schema',
+    description:
+        'The result of the export operation for a project and environment, used at import',
     properties: {
         project: {
             type: 'string',
+            example: 'My awesome project',
+            description:
+                'The exported [project](https://docs.getunleash.io/reference/projects)',
         },
         environment: {
             type: 'string',
+            example: 'development',
+            description:
+                'The exported [environment](https://docs.getunleash.io/reference/environments)',
         },
         data: {
             $ref: '#/components/schemas/exportResultSchema',

src/lib/openapi/spec/import-toggles-validate-item-schema.ts

@@ -8,9 +8,12 @@ export const importTogglesValidateItemSchema = {
     properties: {
         message: {
             type: 'string',
+            description: 'The validation error message',
         },
         affectedItems: {
             type: 'array',
+            description: 'The items affected by this error message ',
+            example: ['some-feature-a', 'some-feature-b'],
             items: {
                 type: 'string',
             },

src/lib/openapi/spec/import-toggles-validate-schema.ts

@@ -6,6 +6,8 @@ export const importTogglesValidateSchema = {
     type: 'object',
     required: ['errors', 'warnings'],
     additionalProperties: false,
+    summary: 'Import toggles validation result schema',
+    description: 'The result of toggle validation after import',
     properties: {
         errors: {
             type: 'array',

src/lib/openapi/util/openapi-tags.ts

@@ -128,6 +128,11 @@ const OPENAPI_TAGS = [
         name: 'Telemetry',
         description: 'API for information about telemetry collection',
     },
+    {
+        name: 'Notifications',
+        description:
+            'API for managing [notifications](https://docs.getunleash.io/reference/notifications).',
+    },
 ] as const;
 
 // make the export mutable, so it can be used in a schema