diff --git a/src/lib/openapi/meta-schema-rules.test.ts b/src/lib/openapi/meta-schema-rules.test.ts index 042baa430c..a4e13056d2 100644 --- 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'], }, ]; diff --git a/src/lib/openapi/spec/__snapshots__/sort-order-schema.test.ts.snap b/src/lib/openapi/spec/__snapshots__/sort-order-schema.test.ts.snap index b2946dba6b..4708d52f7e 100644 --- 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", }, diff --git a/src/lib/openapi/spec/feature-strategy-segment-schema.ts b/src/lib/openapi/spec/feature-strategy-segment-schema.ts index ae473c1a0f..70b6b40e7e 100644 --- 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: {}, diff --git a/src/lib/openapi/spec/group-schema.ts b/src/lib/openapi/spec/group-schema.ts index 3e7e1e70cf..bdde437477 100644 --- 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: { diff --git a/src/lib/openapi/spec/maintenance-schema.ts b/src/lib/openapi/spec/maintenance-schema.ts index e0e9342b12..fa15236e6c 100644 --- 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, }, diff --git a/src/lib/openapi/spec/playground-segment-schema.ts b/src/lib/openapi/spec/playground-segment-schema.ts index 5338a1d49c..03f6948ed7 100644 --- 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: { diff --git a/src/lib/openapi/spec/playground-strategy-schema.ts b/src/lib/openapi/spec/playground-strategy-schema.ts index 4de02c3cd3..3b94cd97b8 100644 --- 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', diff --git a/src/lib/openapi/spec/project-overview-schema.ts b/src/lib/openapi/spec/project-overview-schema.ts index 52f83f5af0..427cd602e5 100644 --- 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', diff --git a/src/lib/openapi/spec/project-schema.ts b/src/lib/openapi/spec/project-schema.ts index ef7e41d7f6..b340d15910 100644 --- 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', diff --git a/src/lib/openapi/spec/projects-schema.ts b/src/lib/openapi/spec/projects-schema.ts index ba2618ef63..496876583d 100644 --- 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', diff --git a/src/lib/openapi/spec/push-variants-schema.ts b/src/lib/openapi/spec/push-variants-schema.ts index 1b41bd52d5..1cd42a5aa9 100644 --- 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', }, diff --git a/src/lib/openapi/spec/reset-password-schema.ts b/src/lib/openapi/spec/reset-password-schema.ts index ff9803f2dd..54f1d66743 100644 --- 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: {}, diff --git a/src/lib/openapi/spec/sdk-context-schema.ts b/src/lib/openapi/spec/sdk-context-schema.ts index 59b6b48e40..8a0b5f4f42 100644 --- 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', diff --git a/src/lib/openapi/spec/sort-order-schema.ts b/src/lib/openapi/spec/sort-order-schema.ts index d809a731bc..bc1e5aa25e 100644 --- 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; diff --git a/src/lib/openapi/spec/state-schema.ts b/src/lib/openapi/spec/state-schema.ts index 63e3b5af00..fc23eba9ef 100644 --- 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', }, diff --git a/src/lib/openapi/spec/toggle-maintenance-schema.ts b/src/lib/openapi/spec/toggle-maintenance-schema.ts index 8c9d76c1c4..2dd8e2d77e 100644 --- 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, }, diff --git a/src/lib/openapi/spec/upsert-context-field-schema.ts b/src/lib/openapi/spec/upsert-context-field-schema.ts index eaaae807f8..787ec0a738 100644 --- 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: { diff --git a/src/lib/openapi/spec/users-groups-base-schema.ts b/src/lib/openapi/spec/users-groups-base-schema.ts index 1cae4f6a28..c4044e2fef 100644 --- 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: { diff --git a/src/lib/openapi/spec/users-search-schema.ts b/src/lib/openapi/spec/users-search-schema.ts index 9a4084a275..4eca72f2f8 100644 --- 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', }, diff --git a/src/lib/openapi/spec/variants-schema.ts b/src/lib/openapi/spec/variants-schema.ts index cdc91fbdaa..e21efd3628 100644 --- 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', }, diff --git a/src/lib/routes/admin-api/maintenance.ts b/src/lib/routes/admin-api/maintenance.ts index fa5fcfb000..3edd68f2b5 100644 --- 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, - res: Response, + req: IAuthRequest, + res: Response, ): Promise { await this.maintenanceService.toggleMaintenanceMode( req.body,