feat: openapi schema for user admin (#4146)

src/lib/error/bad-data-error.ts

@@ -16,7 +16,7 @@ class BadDataError extends UnleashError {
         errors?: [ValidationErrorDescription, ...ValidationErrorDescription[]],
     ) {
         const topLevelMessage =
-            'Request validation failed: your request body contains invalid data' +
+            'Request validation failed: your request body or params contain invalid data' +
             (errors
                 ? '. Refer to the `details` list for more information.'
                 : `: ${message}`);

src/lib/openapi/index.ts

@@ -133,6 +133,7 @@ import {
     userSchema,
     usersGroupsBaseSchema,
     usersSchema,
+    createUserResponseSchema,
     usersSearchSchema,
     validatedEdgeTokensSchema,
     validatePasswordSchema,
@@ -327,6 +328,7 @@ export const schemas: UnleashSchemas = {
     createStrategySchema,
     updateStrategySchema,
     userSchema,
+    createUserResponseSchema,
     usersGroupsBaseSchema,
     usersSchema,
     usersSearchSchema,

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

@@ -96,7 +96,6 @@ const metaRules: Rule[] = [
             'createApiTokenSchema',
             'createFeatureSchema',
             'createInvitedUserSchema',
-            'createUserSchema',
             'environmentsSchema',
             'environmentsProjectSchema',
             'eventSchema',
@@ -113,11 +112,9 @@ const metaRules: Rule[] = [
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
-            'idSchema',
             'maintenanceSchema',
             'toggleMaintenanceSchema',
             'meSchema',
-            'passwordSchema',
             'patchSchema',
             'permissionSchema',
             'profileSchema',
@@ -143,11 +140,9 @@ const metaRules: Rule[] = [
             'updateFeatureSchema',
             'updateFeatureStrategySchema',
             'updateTagTypeSchema',
-            'updateUserSchema',
             'upsertContextFieldSchema',
             'upsertStrategySchema',
             'usersGroupsBaseSchema',
-            'usersSchema',
             'validateEdgeTokensSchema',
             'validateTagTypeSchema',
             'variantFlagSchema',
@@ -175,7 +170,6 @@ const metaRules: Rule[] = [
             'createFeatureSchema',
             'createFeatureStrategySchema',
             'createInvitedUserSchema',
-            'createUserSchema',
             'dateSchema',
             'environmentsSchema',
             'eventSchema',
@@ -191,12 +185,10 @@ const metaRules: Rule[] = [
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
-            'idSchema',
             'maintenanceSchema',
             'toggleMaintenanceSchema',
             'meSchema',
             'parametersSchema',
-            'passwordSchema',
             'patchesSchema',
             'patchSchema',
             'permissionSchema',
@@ -223,11 +215,9 @@ const metaRules: Rule[] = [
             'updateFeatureSchema',
             'updateFeatureStrategySchema',
             'updateTagTypeSchema',
-            'updateUserSchema',
             'upsertContextFieldSchema',
             'upsertStrategySchema',
             'usersGroupsBaseSchema',
-            'usersSchema',
             'usersSearchSchema',
             'validateEdgeTokensSchema',
             'validateTagTypeSchema',

src/lib/openapi/spec/create-user-response-schema.ts

@@ -0,0 +1,34 @@
+import { FromSchema } from 'json-schema-to-ts';
+import { userSchema } from './user-schema';
+
+export const createUserResponseSchema = {
+    $id: '#/components/schemas/createUserResponseSchema',
+    type: 'object',
+    additionalProperties: false,
+    description: 'An Unleash user after creation',
+    required: ['id'],
+    properties: {
+        ...userSchema.properties,
+        rootRole: {
+            description:
+                'Which [root role](https://docs.getunleash.io/reference/rbac#standard-roles) this user is assigned. Usually a numeric role ID, but can be a string when returning newly created user with an explicit string role.',
+            oneOf: [
+                {
+                    type: 'integer',
+                    example: 1,
+                    minimum: 0,
+                },
+                {
+                    type: 'string',
+                    example: 'Admin',
+                    enum: ['Admin', 'Editor', 'Viewer', 'Owner', 'Member'],
+                },
+            ],
+        },
+    },
+    components: {},
+} as const;
+
+export type CreateUserResponseSchema = FromSchema<
+    typeof createUserResponseSchema
+>;

src/lib/openapi/spec/create-user-schema.ts

@@ -5,24 +5,52 @@ export const createUserSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['rootRole'],
+    description:
+        'The payload must contain at least one of the name and email properties, though which one is up to you. For the user to be able to log in to the system, the user must have an email.',
     properties: {
         username: {
+            description:
+                "The user's username. Must be provided if email is not provided.",
             type: 'string',
+            example: 'hunter',
         },
         email: {
+            description:
+                "The user's email address. Must be provided if username is not provided.",
             type: 'string',
+            example: 'user@example.com',
         },
         name: {
+            description: "The user's name (not the user's username).",
             type: 'string',
+            example: 'Sam Seawright',
         },
         password: {
             type: 'string',
+            example: 'k!5As3HquUrQ',
+            description: 'Password for the user',
         },
         rootRole: {
-            type: 'number',
+            description:
+                "The role to assign to the user. Can be either the role's ID or its unique name.",
+            oneOf: [
+                {
+                    type: 'integer',
+                    example: 1,
+                    minimum: 0,
+                },
+                {
+                    type: 'string',
+                    example: 'Admin',
+                    enum: ['Admin', 'Editor', 'Viewer', 'Owner', 'Member'],
+                },
+            ],
         },
         sendEmail: {
             type: 'boolean',
+            example: false,
+            description:
+                'Whether to send a welcome email with a login link to the user or not. Defaults to `true`.',
         },
     },
     components: {},

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

@@ -4,10 +4,13 @@ export const idSchema = {
     $id: '#/components/schemas/idSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'Email id used for password reset',
     required: ['id'],
     properties: {
         id: {
             type: 'string',
+            description: 'User email',
+            example: 'user@example.com',
         },
     },
     components: {},

src/lib/openapi/spec/index.ts

@@ -8,6 +8,7 @@ export * from './pats-schema';
 export * from './role-schema';
 export * from './tags-schema';
 export * from './user-schema';
+export * from './create-user-response-schema';
 export * from './addon-schema';
 export * from './addon-create-update-schema';
 export * from './email-schema';

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

@@ -5,15 +5,24 @@ export const passwordSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['password'],
+    description: 'Fields used to create new password or update old password',
     properties: {
         password: {
             type: 'string',
+            example: 'k!5As3HquUrQ',
+            description: 'The new password to change or validate.',
         },
         oldPassword: {
             type: 'string',
+            example: 'Oldk!5As3HquUrQ',
+            description:
+                'The old password the user is changing. This field is for the non-admin users changing their own password.',
         },
         confirmPassword: {
             type: 'string',
+            example: 'k!5As3HquUrQ',
+            description:
+                'The confirmation of the new password. This field is for the non-admin users changing their own password.',
         },
     },
     components: {},

src/lib/openapi/spec/update-user-schema.ts

@@ -4,15 +4,34 @@ export const updateUserSchema = {
     $id: '#/components/schemas/updateUserSchema',
     type: 'object',
     additionalProperties: true,
+    description: 'All fields that can be directly changed for the user',
     properties: {
         email: {
+            description:
+                "The user's email address. Must be provided if username is not provided.",
             type: 'string',
+            example: 'user@example.com',
         },
         name: {
+            description: "The user's name (not the user's username).",
             type: 'string',
+            example: 'Sam Seawright',
         },
         rootRole: {
-            type: 'number',
+            description:
+                "The role to assign to the user. Can be either the role's ID or its unique name.",
+            oneOf: [
+                {
+                    type: 'integer',
+                    example: 1,
+                    minimum: 0,
+                },
+                {
+                    type: 'string',
+                    example: 'Admin',
+                    enum: ['Admin', 'Editor', 'Viewer', 'Owner', 'Member'],
+                },
+            ],
         },
     },
     components: {},

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

@@ -84,6 +84,13 @@ export const userSchema = {
             enum: AccountTypes,
             example: 'User',
         },
+        permissions: {
+            description: 'Deprecated',
+            type: 'array',
+            items: {
+                type: 'string',
+            },
+        },
     },
     components: {},
 } as const;

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

@@ -6,16 +6,20 @@ export const usersSchema = {
     $id: '#/components/schemas/usersSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'Users and root roles',
     required: ['users'],
     properties: {
         users: {
             type: 'array',
+            description: 'A list of users in the Unleash instance.',
             items: {
                 $ref: '#/components/schemas/userSchema',
             },
         },
         rootRoles: {
             type: 'array',
+            description:
+                'A list of [root roles](https://docs.getunleash.io/reference/rbac#standard-roles) in the Unleash instance.',
             items: {
                 $ref: '#/components/schemas/roleSchema',
             },