OpenAPI: more schema cleanup (#4353)

This PR fixes additional schemas that hadn't been described properly
2025-04-06 01:15:28 +02:00 · 2023-07-28 08:59:05 +02:00 · 2023-07-28 08:59:05 +02:00 · df59b10fb6
commit df59b10fb6
parent 12209ae21c
21 changed files with 96 additions and 38 deletions
--- a/src/lib/openapi/meta-schema-rules.test.ts
+++ b/src/lib/openapi/meta-schema-rules.test.ts
@ -90,21 +90,8 @@ const metaRules: Rule[] = [
            },
        },
        knownExceptions: [
-            'featureStrategySegmentSchema',
-            'maintenanceSchema',
-            'toggleMaintenanceSchema',
            'patchSchema',
-            'projectSchema',
-            'projectsSchema',
-            'pushVariantsSchema',
-            'resetPasswordSchema',
-            'sdkContextSchema',
-            'stateSchema',
-            'upsertContextFieldSchema',
-            'upsertStrategySchema',
-            'usersGroupsBaseSchema',
-            'validateEdgeTokensSchema',
-            'projectOverviewSchema',
+            'upsertContextFieldSchema', // must be split. Name can't be updated
        ],
    },
    {
@ -116,23 +103,7 @@ const metaRules: Rule[] = [
            },
            required: ['description'],
        },
-        knownExceptions: [
-            'featureStrategySegmentSchema',
-            'maintenanceSchema',
-            'toggleMaintenanceSchema',
-            'patchSchema',
-            'playgroundSegmentSchema',
-            'playgroundStrategySchema',
-            'pushVariantsSchema',
-            'resetPasswordSchema',
-            'sortOrderSchema',
-            'upsertContextFieldSchema',
-            'upsertStrategySchema',
-            'usersGroupsBaseSchema',
-            'usersSearchSchema',
-            'validateEdgeTokensSchema',
-            'variantsSchema',
-        ],
+        knownExceptions: ['patchSchema'],
    },
 ];

--- a/src/lib/openapi/spec/snapshots/sort-order-schema.test.ts.snap
+++ b/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",
    },
--- a/src/lib/openapi/spec/feature-strategy-segment-schema.ts
+++ b/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: {},
--- a/src/lib/openapi/spec/group-schema.ts
+++ b/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: {
--- a/src/lib/openapi/spec/maintenance-schema.ts
+++ b/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,
        },
--- a/src/lib/openapi/spec/playground-segment-schema.ts
+++ b/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: {
--- a/src/lib/openapi/spec/playground-strategy-schema.ts
+++ b/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',
--- a/src/lib/openapi/spec/project-overview-schema.ts
+++ b/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',
--- a/src/lib/openapi/spec/project-schema.ts
+++ b/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',
--- a/src/lib/openapi/spec/projects-schema.ts
+++ b/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',
--- a/src/lib/openapi/spec/push-variants-schema.ts
+++ b/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',
            },
--- a/src/lib/openapi/spec/reset-password-schema.ts
+++ b/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: {},
--- a/src/lib/openapi/spec/sdk-context-schema.ts
+++ b/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',
--- a/src/lib/openapi/spec/sort-order-schema.ts
+++ b/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;
--- a/src/lib/openapi/spec/state-schema.ts
+++ b/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',
            },
--- a/src/lib/openapi/spec/toggle-maintenance-schema.ts
+++ b/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,
        },
--- a/src/lib/openapi/spec/upsert-context-field-schema.ts
+++ b/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: {
--- a/src/lib/openapi/spec/users-groups-base-schema.ts
+++ b/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: {
--- a/src/lib/openapi/spec/users-search-schema.ts
+++ b/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',
    },
--- a/src/lib/openapi/spec/variants-schema.ts
+++ b/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',
    },
--- a/src/lib/routes/admin-api/maintenance.ts
+++ b/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>,
-        res: Response,
+        req: IAuthRequest<unknown, unknown, ToggleMaintenanceSchema>,
+        res: Response<MaintenanceSchema>,
    ): Promise<void> {
        await this.maintenanceService.toggleMaintenanceMode(
            req.body,