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/meta-schema-rules.test.ts

@@ -103,8 +103,6 @@ const metaRules: Rule[] = [
             'environmentsProjectSchema',
             'eventSchema',
             'eventsSchema',
-            'exportResultSchema',
-            'exportQuerySchema',
             'featureEnvironmentSchema',
             'featureEventsSchema',
             'featureSchema',
@@ -163,9 +161,6 @@ const metaRules: Rule[] = [
             'variantFlagSchema',
             'versionSchema',
             'projectOverviewSchema',
-            'importTogglesSchema',
-            'importTogglesValidateSchema',
-            'importTogglesValidateItemSchema',
         ],
     },
     {
@@ -195,8 +190,6 @@ const metaRules: Rule[] = [
             'environmentsSchema',
             'eventSchema',
             'eventsSchema',
-            'exportResultSchema',
-            'exportQuerySchema',
             'featureEventsSchema',
             'featureSchema',
             'featuresSchema',
@@ -257,9 +250,6 @@ const metaRules: Rule[] = [
             'variantFlagSchema',
             'variantsSchema',
             'versionSchema',
-            'importTogglesSchema',
-            'importTogglesValidateSchema',
-            'importTogglesValidateItemSchema',
         ],
     },
 ];

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

@@ -5,12 +5,18 @@ export const exportQuerySchema = {
     type: 'object',
     additionalProperties: true,
     required: ['environment'],
+    description:
+        'Available query parameters for  the [deprecated export/import](https://docs.getunleash.io/reference/deploy/import-export) functionality.',
     properties: {
         environment: {
             type: 'string',
+            example: 'development',
+            description: 'The environment to export from',
         },
         downloadFile: {
             type: 'boolean',
+            example: true,
+            description: 'Whether to return a downloadable file',
         },
     },
     oneOf: [
@@ -19,6 +25,7 @@ export const exportQuerySchema = {
             properties: {
                 features: {
                     type: 'array',
+                    example: ['MyAwesomeFeature'],
                     items: {
                         type: 'string',
                         minLength: 1,
@@ -32,6 +39,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,40 +16,126 @@ 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.)',
     required: ['features', 'featureStrategies', 'tagTypes'],
     properties: {
         features: {
             type: 'array',
+            description: 'All the exported features.',
+            example: [
+                {
+                    name: 'my-feature',
+                    description: 'best feature ever',
+                    type: 'release',
+                    project: 'default',
+                    stale: false,
+                    impressionData: false,
+                    archived: false,
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/featureSchema',
             },
         },
         featureStrategies: {
             type: 'array',
+            description:
+                'All strategy instances that are used by the exported features in the `features` list.',
+            example: [
+                {
+                    name: 'flexibleRollout',
+                    id: '924974d7-8003-43ee-87eb-c5f887c06fd1',
+                    featureName: 'my-feature',
+                    title: 'Rollout 50%',
+                    parameters: {
+                        groupId: 'default',
+                        rollout: '50',
+                        stickiness: 'random',
+                    },
+                    constraints: [],
+                    disabled: false,
+                    segments: [1],
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/featureStrategySchema',
             },
         },
         featureEnvironments: {
             type: 'array',
+            description:
+                'Environment-specific configuration for all the features in the `features` list. Includes data such as whether the feature is enabled in the selected export environment, whether there are any variants assigned, etc.',
+            example: [
+                {
+                    enabled: true,
+                    featureName: 'my-feature',
+                    environment: 'development',
+                    variants: [
+                        {
+                            name: 'a',
+                            weight: 500,
+                            overrides: [],
+                            stickiness: 'random',
+                            weightType: 'variable',
+                        },
+                        {
+                            name: 'b',
+                            weight: 500,
+                            overrides: [],
+                            stickiness: 'random',
+                            weightType: 'variable',
+                        },
+                    ],
+                    name: 'variant-testing',
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/featureEnvironmentSchema',
             },
         },
         contextFields: {
             type: 'array',
+            description:
+                'A list of all the context fields that are in use by any of the strategies in the `featureStrategies` list.',
+            example: [
+                {
+                    name: 'appName',
+                    description: 'Allows you to constrain on application name',
+                    stickiness: false,
+                    sortOrder: 2,
+                    legalValues: [],
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/contextFieldSchema',
             },
         },
         featureTags: {
             type: 'array',
+            description:
+                'A list of all the tags that have been applied to any of the features in the `features` list.',
+            example: [
+                {
+                    featureName: 'my-feature',
+                    tagType: 'simple',
+                    tagValue: 'user-facing',
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/featureTagSchema',
             },
         },
         segments: {
             type: 'array',
+            description:
+                'A list of all the segments that are used by the strategies in the `featureStrategies` list.',
+            example: [
+                {
+                    id: 1,
+                    name: 'new-segment-name',
+                },
+            ],
             items: {
                 type: 'object',
                 additionalProperties: false,
@@ -66,6 +152,15 @@ export const exportResultSchema = {
         },
         tagTypes: {
             type: 'array',
+            description:
+                'A list of all of the tag types that are used in the `featureTags` list.',
+            example: [
+                {
+                    name: 'simple',
+                    description: 'Used to simplify filtering of features',
+                    icon: '#',
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/tagTypeSchema',
             },

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

@@ -19,12 +19,20 @@ export const importTogglesSchema = {
     type: 'object',
     required: ['project', 'environment', 'data'],
     additionalProperties: false,
+    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

@@ -5,12 +5,19 @@ export const importTogglesValidateItemSchema = {
     type: 'object',
     required: ['message', 'affectedItems'],
     additionalProperties: false,
+    description:
+        'A description of an error or warning pertaining to a feature toggle import job.',
     properties: {
         message: {
             type: 'string',
+            description: 'The validation error message',
+            example:
+                'You cannot import a feature that already exist in other projects. You already have the following features defined outside of project default:',
         },
         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,24 +6,46 @@ export const importTogglesValidateSchema = {
     type: 'object',
     required: ['errors', 'warnings'],
     additionalProperties: false,
+    description:
+        'An object containing [feature import](https://docs.getunleash.io/reference/deploy/environment-import-export) validation results.',
     properties: {
         errors: {
+            description:
+                'A list of errors that prevent the provided data from being successfully imported.',
             type: 'array',
+            example: [
+                {
+                    message:
+                        'You cannot import a feature that already exist in other projects. You already have the following features defined outside of project default:',
+                    affectedItems: ['my-feature (in project project-854)'],
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/importTogglesValidateItemSchema',
             },
         },
         warnings: {
             type: 'array',
+            description: 'A list of warnings related to the provided data.',
+            example: [
+                {
+                    message:
+                        'The following strategy types will be used in import. Please make sure the strategy type parameters are configured as in source environment:',
+                    affectedItems: ['custom-strategy-7'],
+                },
+            ],
             items: {
                 $ref: '#/components/schemas/importTogglesValidateItemSchema',
             },
         },
         permissions: {
             type: 'array',
+            description:
+                'Any additional permissions required to import the data. If the list is empty, you require no additional permissions beyond what your user already has.',
             items: {
                 $ref: '#/components/schemas/importTogglesValidateItemSchema',
             },
+            example: [],
         },
     },
     components: {