OpenAPI: more schema cleanup (#4353)

This PR fixes additional schemas that hadn't been described properly

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

@@ -90,21 +90,8 @@ const metaRules: Rule[] = [
             },
         },
         knownExceptions: [
-            'featureStrategySegmentSchema',
-            'maintenanceSchema',
-            'toggleMaintenanceSchema',
             'patchSchema',
-            'projectSchema',
+            'upsertContextFieldSchema', // must be split. Name can't be updated
-            'projectsSchema',
-            'pushVariantsSchema',
-            'resetPasswordSchema',
-            'sdkContextSchema',
-            'stateSchema',
-            'upsertContextFieldSchema',
-            'upsertStrategySchema',
-            'usersGroupsBaseSchema',
-            'validateEdgeTokensSchema',
-            'projectOverviewSchema',
         ],
     },
     {
@@ -116,23 +103,7 @@ const metaRules: Rule[] = [
             },
             required: ['description'],
         },
-        knownExceptions: [
+        knownExceptions: ['patchSchema'],
-            'featureStrategySegmentSchema',
-            'maintenanceSchema',
-            'toggleMaintenanceSchema',
-            'patchSchema',
-            'playgroundSegmentSchema',
-            'playgroundStrategySchema',
-            'pushVariantsSchema',
-            'resetPasswordSchema',
-            'sortOrderSchema',
-            'upsertContextFieldSchema',
-            'upsertStrategySchema',
-            'usersGroupsBaseSchema',
-            'usersSearchSchema',
-            'validateEdgeTokensSchema',
-            'variantsSchema',
-        ],
     },
 ];
 

src/lib/openapi/spec/__snapshots__/sort-order-schema.test.ts.snap

@@ -6,9 +6,9 @@ exports[`sortOrderSchema invalid value type 1`] = `
     {
       "instancePath": "/a",
       "keyword": "type",
-      "message": "must be number",
+      "message": "must be integer",
       "params": {
-        "type": "number",
+        "type": "integer",
       },
       "schemaPath": "#/additionalProperties/type",
     },

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

@@ -3,14 +3,20 @@ import { FromSchema } from 'json-schema-to-ts';
 export const featureStrategySegmentSchema = {
     $id: '#/components/schemas/featureStrategySegmentSchema',
     type: 'object',
+    description:
+        'An object containing a segment identifier and a strategy identifier.',
     additionalProperties: false,
     required: ['segmentId', 'featureStrategyId'],
     properties: {
         segmentId: {
             type: 'integer',
+            description: 'The ID of the segment',
+            example: 2,
         },
         featureStrategyId: {
             type: 'string',
+            description: 'The ID of the strategy',
+            example: 'e2caa08f-30c4-4aa3-b955-54ca9e93dc13',
         },
     },
     components: {},

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

@@ -69,6 +69,12 @@ export const groupSchema = {
             },
             example: ['default', 'my-project'],
         },
+        userCount: {
+            description: 'The number of users that belong to this group',
+            example: 1,
+            type: 'integer',
+            minimum: 0,
+        },
     },
     components: {
         schemas: {

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

@@ -4,9 +4,11 @@ export const maintenanceSchema = {
     $id: '#/components/schemas/maintenanceSchema',
     type: 'object',
     additionalProperties: false,
+    description: "The current state of Unleash's maintenance mode feature.",
     required: ['enabled'],
     properties: {
         enabled: {
+            description: 'Whether maintenance mode is enabled or not.',
             type: 'boolean',
             example: true,
         },

src/lib/openapi/spec/playground-segment-schema.ts

@@ -5,6 +5,7 @@ export const playgroundSegmentSchema = {
     $id: '#/components/schemas/playgroundSegmentSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'The evaluated result of a segment as used by the Playground.',
     required: ['name', 'id', 'constraints', 'result'],
     properties: {
         id: {

src/lib/openapi/spec/playground-strategy-schema.ts

@@ -110,6 +110,8 @@ export const strategyEvaluationResults = {
 export const playgroundStrategySchema = {
     $id: '#/components/schemas/playgroundStrategySchema',
     type: 'object',
+    description:
+        'An evaluated feature toggle strategy as used by the Playground',
     additionalProperties: false,
     required: [
         'id',

src/lib/openapi/spec/project-overview-schema.ts

@@ -26,8 +26,10 @@ export const projectOverviewSchema = {
             description: 'Project statistics',
         },
         version: {
-            type: 'number',
+            type: 'integer',
             example: 1,
+            description:
+                'The schema version used to describe the project overview',
         },
         name: {
             type: 'string',
@@ -106,12 +108,14 @@ export const projectOverviewSchema = {
             format: 'date-time',
             nullable: true,
             example: '2023-02-10T08:36:35.262Z',
+            description: 'When the project was last updated.',
         },
         createdAt: {
             type: 'string',
             format: 'date-time',
             nullable: true,
             example: '2023-02-10T08:36:35.262Z',
+            description: 'When the project was created.',
         },
         favorite: {
             type: 'boolean',

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

@@ -42,12 +42,16 @@ export const projectSchema = {
         },
         createdAt: {
             type: 'string',
+            description: 'When this project was created.',
+            example: '2023-07-27T12:12:28Z',
             format: 'date-time',
         },
         updatedAt: {
             type: 'string',
             format: 'date-time',
             nullable: true,
+            description: 'When this project was last updated.',
+            example: '2023-07-28T12:12:28Z',
         },
         favorite: {
             type: 'boolean',

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

@@ -10,6 +10,9 @@ export const projectsSchema = {
     properties: {
         version: {
             type: 'integer',
+            description:
+                'The schema version used to represent the project data.',
+            example: 1,
         },
         projects: {
             type: 'array',

src/lib/openapi/spec/push-variants-schema.ts

@@ -5,15 +5,18 @@ import { overrideSchema } from './override-schema';
 export const pushVariantsSchema = {
     $id: '#/components/schemas/pushVariantsSchema',
     type: 'object',
+    description: 'Data used when copying variants into a new environment.',
     properties: {
         variants: {
             type: 'array',
+            description: 'The variants to write to the provided environments',
             items: {
                 $ref: '#/components/schemas/variantSchema',
             },
         },
         environments: {
             type: 'array',
+            description: 'The enviromnents to write the provided variants to',
             items: {
                 type: 'string',
             },

src/lib/openapi/spec/reset-password-schema.ts

@@ -3,11 +3,16 @@ import { FromSchema } from 'json-schema-to-ts';
 export const resetPasswordSchema = {
     $id: '#/components/schemas/resetPasswordSchema',
     type: 'object',
+    description: 'Data used to provide users a way to reset their passwords.',
     additionalProperties: false,
     required: ['resetPasswordUrl'],
     properties: {
         resetPasswordUrl: {
+            description:
+                'A URL pointing to a location where the user can reset their password',
             type: 'string',
+            format: 'uri',
+            example: 'https://reset.password.com',
         },
     },
     components: {},

src/lib/openapi/spec/sdk-context-schema.ts

@@ -28,6 +28,7 @@ export const sdkContextSchema = {
         properties: {
             type: 'object',
             additionalProperties: { type: 'string' },
+            description: 'Additional Unleash context properties',
             example: {
                 customContextField: 'this is one!',
                 otherCustomField: '3',

src/lib/openapi/spec/sort-order-schema.ts

@@ -3,8 +3,12 @@ import { FromSchema } from 'json-schema-to-ts';
 export const sortOrderSchema = {
     $id: '#/components/schemas/sortOrderSchema',
     type: 'object',
+    description: 'A map of object IDs and their corresponding sort orders.',
     additionalProperties: {
-        type: 'number',
+        type: 'integer',
+        description:
+            'Sort order for the object whose ID is the key used for this property.',
+        example: 6,
     },
     components: {},
 } as const;

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

@@ -18,74 +18,87 @@ export const stateSchema = {
     additionalProperties: true,
     deprecated: true,
     description:
-        'The state of the application used by export/import APIs which are deprecated in favor of the more fine grained /api/admin/export and /api/admin/import APIs',
+        'The application state as used by the deprecated export/import APIs.',
     required: ['version'],
     properties: {
         version: {
             type: 'integer',
+            description: 'The version of the schema used to describe the state',
+            example: 1,
         },
         features: {
             type: 'array',
+            description: 'A list of features',
             items: {
                 $ref: '#/components/schemas/featureSchema',
             },
         },
         strategies: {
             type: 'array',
+            description: 'A list of strategies',
             items: {
                 $ref: '#/components/schemas/strategySchema',
             },
         },
         tags: {
             type: 'array',
+            description: 'A list of tags',
             items: {
                 $ref: '#/components/schemas/tagSchema',
             },
         },
         tagTypes: {
             type: 'array',
+            description: 'A list of tag types',
             items: {
                 $ref: '#/components/schemas/tagTypeSchema',
             },
         },
         featureTags: {
             type: 'array',
+            description: 'A list of tags applied to features',
             items: {
                 $ref: '#/components/schemas/featureTagSchema',
             },
         },
         projects: {
             type: 'array',
+            description: 'A list of projects',
             items: {
                 $ref: '#/components/schemas/projectSchema',
             },
         },
         featureStrategies: {
             type: 'array',
+            description: 'A list of feature strategies as applied to features',
             items: {
                 $ref: '#/components/schemas/featureStrategySchema',
             },
         },
         featureEnvironments: {
             type: 'array',
+            description: 'A list of feature environment configurations',
             items: {
                 $ref: '#/components/schemas/featureEnvironmentSchema',
             },
         },
         environments: {
             type: 'array',
+            description: 'A list of environments',
             items: {
                 $ref: '#/components/schemas/environmentSchema',
             },
         },
         segments: {
             type: 'array',
+            description: 'A list of segments',
             items: {
                 $ref: '#/components/schemas/segmentSchema',
             },
         },
         featureStrategySegments: {
             type: 'array',
+            description: 'A list of segment/strategy pairings',
             items: {
                 $ref: '#/components/schemas/featureStrategySegmentSchema',
             },

src/lib/openapi/spec/toggle-maintenance-schema.ts

@@ -3,9 +3,13 @@ import { FromSchema } from 'json-schema-to-ts';
 export const toggleMaintenanceSchema = {
     $id: '#/components/schemas/toggleMaintenanceSchema',
     type: 'object',
+    description:
+        'Data used when to activate or deactivate maintenance mode for Unleash.',
     required: ['enabled'],
     properties: {
         enabled: {
+            description:
+                '`true` if you want to activate maintenance mode, `false` if you want to deactivate it.',
             type: 'boolean',
             example: true,
         },

src/lib/openapi/spec/upsert-context-field-schema.ts

@@ -4,9 +4,11 @@ import { legalValueSchema } from './legal-value-schema';
 export const upsertContextFieldSchema = {
     $id: '#/components/schemas/upsertContextFieldSchema',
     type: 'object',
+    description: 'Data to create or update a context field configuration.',
     required: ['name'],
     properties: {
         name: {
+            description: 'The name of the context field.',
             type: 'string',
         },
         description: {

src/lib/openapi/spec/users-groups-base-schema.ts

@@ -7,18 +7,42 @@ export const usersGroupsBaseSchema = {
     $id: '#/components/schemas/usersGroupsBaseSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'An overview of user groups and users.',
     properties: {
         groups: {
             type: 'array',
+            description: 'A list of user groups and their configuration.',
             items: {
                 $ref: '#/components/schemas/groupSchema',
             },
+            example: [
+                {
+                    id: 1,
+                    name: 'unleash-e2e-7095756699593281',
+                    userCount: 1,
+                    rootRole: null,
+                },
+            ],
         },
         users: {
             type: 'array',
             items: {
                 $ref: '#/components/schemas/userSchema',
             },
+            description: 'A list of users.',
+            example: [
+                {
+                    id: 4,
+                    name: 'unleash-e2e-user2-7095756699593281',
+                    email: 'unleash-e2e-user2-7095756699593281@test.com',
+                    accountType: 'User',
+                },
+                {
+                    id: 1,
+                    username: 'admin',
+                    accountType: 'User',
+                },
+            ],
         },
     },
     components: {

src/lib/openapi/spec/users-search-schema.ts

@@ -4,6 +4,7 @@ import { userSchema } from './user-schema';
 export const usersSearchSchema = {
     $id: '#/components/schemas/usersSearchSchema',
     type: 'array',
+    description: 'A list of users',
     items: {
         $ref: '#/components/schemas/userSchema',
     },

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

@@ -5,6 +5,7 @@ import { overrideSchema } from './override-schema';
 export const variantsSchema = {
     $id: '#/components/schemas/variantsSchema',
     type: 'array',
+    description: 'A list of variants',
     items: {
         $ref: '#/components/schemas/variantSchema',
     },

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

@@ -16,6 +16,7 @@ import {
     maintenanceSchema,
 } from '../../openapi/spec/maintenance-schema';
 import MaintenanceService from 'lib/services/maintenance-service';
+import { ToggleMaintenanceSchema } from 'lib/openapi/spec/toggle-maintenance-schema';
 
 export default class MaintenanceController extends Controller {
     private maintenanceService: MaintenanceService;
@@ -77,8 +78,8 @@ export default class MaintenanceController extends Controller {
     }
 
     async toggleMaintenance(
-        req: IAuthRequest<unknown, unknown, MaintenanceSchema>,
+        req: IAuthRequest<unknown, unknown, ToggleMaintenanceSchema>,
-        res: Response,
+        res: Response<MaintenanceSchema>,
     ): Promise<void> {
         await this.maintenanceService.toggleMaintenanceMode(
             req.body,