OpenAPI - feature environment endpoints (#4166)

## About the changes
Fix OpenAPI definitions for endpoint

`/api/admin/projects/{projectId}/features/{featureName}/environments/{environment}`
and similar.

src/lib/openapi/meta-schema-rules.test.ts

@@ -90,7 +90,6 @@ const metaRules: Rule[] = [
             },
         },
         knownExceptions: [
-            'batchFeaturesSchema',
             'batchStaleSchema',
             'cloneFeatureSchema',
             'createFeatureSchema',
@@ -98,7 +97,6 @@ const metaRules: Rule[] = [
             'environmentsSchema',
             'environmentsProjectSchema',
             'featureEnvironmentSchema',
-            'featureSchema',
             'featuresSchema',
             'featureStrategySegmentSchema',
             'featureTypeSchema',
@@ -150,7 +148,6 @@ const metaRules: Rule[] = [
             'adminFeaturesQuerySchema',
             'applicationSchema',
             'applicationsSchema',
-            'batchFeaturesSchema',
             'batchStaleSchema',
             'cloneFeatureSchema',
             'createFeatureSchema',
@@ -158,7 +155,6 @@ const metaRules: Rule[] = [
             'createInvitedUserSchema',
             'dateSchema',
             'environmentsSchema',
-            'featureSchema',
             'featuresSchema',
             'featureStrategySegmentSchema',
             'featureTypeSchema',
@@ -169,7 +165,6 @@ const metaRules: Rule[] = [
             'groupUserModelSchema',
             'maintenanceSchema',
             'toggleMaintenanceSchema',
-            'parametersSchema',
             'patchesSchema',
             'patchSchema',
             'playgroundSegmentSchema',

src/lib/openapi/spec/batch-features-schema.ts

@@ -3,6 +3,7 @@ import { FromSchema } from 'json-schema-to-ts';
 export const batchFeaturesSchema = {
     $id: '#/components/schemas/batchFeaturesSchema',
     type: 'object',
+    description: 'A list of feature toggle names for batch operations',
     required: ['features'],
     properties: {
         features: {
@@ -10,6 +11,7 @@ export const batchFeaturesSchema = {
             items: {
                 type: 'string',
             },
+            description: 'List of feature toggle names',
         },
     },
     components: {

src/lib/openapi/spec/feature-environment-schema.ts

@@ -42,6 +42,7 @@ export const featureEnvironmentSchema = {
         },
         variantCount: {
             type: 'number',
+            description: 'The number of defined variants',
         },
         strategies: {
             type: 'array',

src/lib/openapi/spec/feature-schema.ts

@@ -12,6 +12,7 @@ export const featureSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['name'],
+    description: 'A feature toggle definition',
     properties: {
         name: {
             type: 'string',
@@ -44,6 +45,7 @@ export const featureSchema = {
         enabled: {
             type: 'boolean',
             example: true,
+            description: '`true` if the feature is enabled, otherwise `false`.',
         },
         stale: {
             type: 'boolean',
@@ -68,18 +70,22 @@ export const featureSchema = {
             format: 'date-time',
             nullable: true,
             example: '2023-01-28T15:21:39.975Z',
+            description: 'The date the feature was created',
         },
         archivedAt: {
             type: 'string',
             format: 'date-time',
             nullable: true,
             example: '2023-01-29T15:21:39.975Z',
+            description: 'The date the feature was archived',
         },
         lastSeenAt: {
             type: 'string',
             format: 'date-time',
             nullable: true,
             example: '2023-01-28T16:21:39.975Z',
+            description:
+                'The date when metrics where last collected for the feature',
         },
         environments: {
             type: 'array',

src/lib/openapi/spec/parameters-schema.ts

@@ -3,6 +3,7 @@ import { FromSchema } from 'json-schema-to-ts';
 export const parametersSchema = {
     $id: '#/components/schemas/parametersSchema',
     type: 'object',
+    description: 'A list of parameters for a strategy',
     additionalProperties: {
         type: 'string',
     },

src/lib/routes/admin-api/feature.ts

@@ -161,7 +161,7 @@ class FeatureController extends Controller {
                     operationId: 'removeTag',
                     responses: {
                         200: emptyResponse,
-                        ...getStandardResponses(404),
+                        ...getStandardResponses(401, 403, 404),
                     },
                 }),
             ],

src/lib/routes/admin-api/project/project-features.ts

@@ -152,10 +152,14 @@ export default class ProjectFeaturesController extends Controller {
             handler: this.getFeatureEnvironment,
             middleware: [
                 openApiService.validPath({
+                    summary: 'Get a feature environment.',
+                    description:
+                        'Information about the enablement status and strategies for a feature toggle in specified environment.',
                     tags: ['Features'],
                     operationId: 'getFeatureEnvironment',
                     responses: {
                         200: createResponseSchema('featureEnvironmentSchema'),
+                        ...getStandardResponses(401, 403, 404),
                     },
                 }),
             ],
@@ -169,9 +173,15 @@ export default class ProjectFeaturesController extends Controller {
             permission: UPDATE_FEATURE_ENVIRONMENT,
             middleware: [
                 openApiService.validPath({
+                    summary: 'Disable a feature toggle.',
+                    description:
+                        'Disable a feature toggle in the specified environment.',
                     tags: ['Features'],
                     operationId: 'toggleFeatureEnvironmentOff',
-                    responses: { 200: createResponseSchema('featureSchema') },
+                    responses: {
+                        200: createResponseSchema('featureSchema'),
+                        ...getStandardResponses(400, 401, 403, 404),
+                    },
                 }),
             ],
         });
@@ -184,9 +194,15 @@ export default class ProjectFeaturesController extends Controller {
             permission: UPDATE_FEATURE_ENVIRONMENT,
             middleware: [
                 openApiService.validPath({
+                    summary: 'Enable a feature toggle.',
+                    description:
+                        'Enable a feature toggle in the specified environment.',
                     tags: ['Features'],
                     operationId: 'toggleFeatureEnvironmentOn',
-                    responses: { 200: createResponseSchema('featureSchema') },
+                    responses: {
+                        200: createResponseSchema('featureSchema'),
+                        ...getStandardResponses(400, 401, 403, 404),
+                    },
                 }),
             ],
         });
@@ -206,7 +222,10 @@ export default class ProjectFeaturesController extends Controller {
                     requestBody: createRequestSchema(
                         'bulkToggleFeaturesSchema',
                     ),
-                    responses: { 405: emptyResponse },
+                    responses: {
+                        200: emptyResponse,
+                        ...getStandardResponses(400, 401, 403, 404, 413, 415),
+                    },
                 }),
             ],
         });
@@ -226,7 +245,10 @@ export default class ProjectFeaturesController extends Controller {
                     requestBody: createRequestSchema(
                         'bulkToggleFeaturesSchema',
                     ),
-                    responses: { 405: emptyResponse },
+                    responses: {
+                        200: emptyResponse,
+                        ...getStandardResponses(400, 401, 403, 404, 413, 415),
+                    },
                 }),
             ],
         });