feat: user openapi spec (#4162)

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

@@ -104,21 +104,14 @@ const metaRules: Rule[] = [
             'featureTypeSchema',
             'featureTypesSchema',
             'featureVariantsSchema',
-            'feedbackSchema',
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
             'maintenanceSchema',
             'toggleMaintenanceSchema',
-            'meSchema',
             'patchSchema',
-            'permissionSchema',
-            'profileSchema',
             'projectSchema',
             'projectsSchema',
-            'proxyClientSchema',
-            'proxyFeatureSchema',
-            'proxyFeaturesSchema',
             'pushVariantsSchema',
             'resetPasswordSchema',
             'requestsPerSecondSchema',
@@ -171,23 +164,16 @@ const metaRules: Rule[] = [
             'featureTypeSchema',
             'featureTypesSchema',
             'featureVariantsSchema',
-            'feedbackSchema',
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
             'maintenanceSchema',
             'toggleMaintenanceSchema',
-            'meSchema',
             'parametersSchema',
             'patchesSchema',
             'patchSchema',
-            'permissionSchema',
             'playgroundSegmentSchema',
             'playgroundStrategySchema',
-            'profileSchema',
-            'proxyClientSchema',
-            'proxyFeatureSchema',
-            'proxyFeaturesSchema',
             'pushVariantsSchema',
             'resetPasswordSchema',
             'requestsPerSecondSchema',

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

@@ -4,20 +4,30 @@ export const feedbackSchema = {
     $id: '#/components/schemas/feedbackSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'User feedback information',
     properties: {
         userId: {
-            type: 'number',
+            description: 'Identifier of the current user giving feedback',
+            type: 'integer',
+            example: 2,
         },
         feedbackId: {
+            description: 'The name of the feedback session',
             type: 'string',
+            example: 'pnps',
         },
         neverShow: {
+            description:
+                '`true` when user opts-in to never show the feedback again.',
             type: 'boolean',
+            example: false,
         },
         given: {
+            description: 'When this feedback was given',
             type: 'string',
             format: 'date-time',
             nullable: true,
+            example: '2023-07-06T08:29:21.282Z',
         },
     },
     components: {},

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

@@ -8,23 +8,27 @@ export const meSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['user', 'permissions', 'feedback', 'splash'],
+    description: 'Detailed user information',
     properties: {
         user: {
             $ref: '#/components/schemas/userSchema',
         },
         permissions: {
+            description: 'User permissions for projects and environments',
             type: 'array',
             items: {
                 $ref: '#/components/schemas/permissionSchema',
             },
         },
         feedback: {
+            description: 'User feedback information',
             type: 'array',
             items: {
                 $ref: '#/components/schemas/feedbackSchema',
             },
         },
         splash: {
+            description: 'Splash screen configuration',
             type: 'object',
             additionalProperties: {
                 type: 'boolean',

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

@@ -5,15 +5,23 @@ export const permissionSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['permission'],
+    description: 'Project and environment permissions',
     properties: {
         permission: {
+            description:
+                '[Project](https://docs.getunleash.io/reference/rbac#project-permissions) or [environment](https://docs.getunleash.io/reference/rbac#environment-permissions) permission name',
             type: 'string',
+            example: 'UPDATE_FEATURE_STRATEGY',
         },
         project: {
+            description: 'The project this permission applies to',
             type: 'string',
+            example: 'my-project',
         },
         environment: {
+            description: 'The environment this permission applies to',
             type: 'string',
+            example: 'development',
         },
     },
     components: {},

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

@@ -6,22 +6,27 @@ export const profileSchema = {
     $id: '#/components/schemas/profileSchema',
     type: 'object',
     additionalProperties: false,
+    description: 'User profile overview',
     required: ['rootRole', 'projects', 'features'],
     properties: {
         rootRole: {
             $ref: '#/components/schemas/roleSchema',
         },
         projects: {
+            description: 'Which projects this user is a member of',
             type: 'array',
             items: {
                 type: 'string',
             },
+            example: ['my-projectA', 'my-projectB'],
         },
         features: {
+            description: 'Deprecated, always returns empty array',
             type: 'array',
             items: {
                 $ref: '#/components/schemas/featureSchema',
             },
+            example: [],
         },
     },
     components: {

src/lib/openapi/spec/proxy-client-schema.ts

@@ -4,6 +4,7 @@ export const proxyClientSchema = {
     $id: '#/components/schemas/proxyClientSchema',
     type: 'object',
     required: ['appName', 'interval', 'started', 'strategies'],
+    description: 'Frontend SDK client registration information',
     properties: {
         appName: {
             type: 'string',
@@ -22,6 +23,8 @@ export const proxyClientSchema = {
         environment: {
             type: 'string',
             deprecated: true,
+            description: 'deprecated',
+            example: 'development',
         },
         interval: {
             type: 'number',

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

@@ -6,6 +6,7 @@ export const proxyFeatureSchema = {
     type: 'object',
     required: ['name', 'enabled', 'impressionData'],
     additionalProperties: false,
+    description: 'Frontend API feature',
     properties: {
         name: {
             type: 'string',
@@ -27,6 +28,7 @@ export const proxyFeatureSchema = {
             type: 'object',
             required: ['name', 'enabled'],
             additionalProperties: false,
+            description: 'Variant details',
             properties: {
                 name: {
                     type: 'string',

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

@@ -6,8 +6,10 @@ export const proxyFeaturesSchema = {
     type: 'object',
     required: ['toggles'],
     additionalProperties: false,
+    description: 'Frontend SDK features list',
     properties: {
         toggles: {
+            description: 'The actual features returned to the Frontend SDK',
             type: 'array',
             items: {
                 $ref: proxyFeatureSchema.$id,

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

@@ -15,7 +15,10 @@ import { meSchema, MeSchema } from '../../../openapi/spec/me-schema';
 import { serializeDates } from '../../../types/serialize-dates';
 import { IUserPermission } from '../../../types/stores/access-store';
 import { PasswordSchema } from '../../../openapi/spec/password-schema';
-import { emptyResponse } from '../../../openapi/util/standard-responses';
+import {
+    emptyResponse,
+    getStandardResponses,
+} from '../../../openapi/util/standard-responses';
 import {
     profileSchema,
     ProfileSchema,
@@ -71,7 +74,13 @@ class UserController extends Controller {
                 openApiService.validPath({
                     tags: ['Users'],
                     operationId: 'getMe',
-                    responses: { 200: createResponseSchema('meSchema') },
+                    summary: 'Get your own user details',
+                    description:
+                        'Detailed information about the current user, user permissions and user feedback',
+                    responses: {
+                        200: createResponseSchema('meSchema'),
+                        ...getStandardResponses(401),
+                    },
                 }),
             ],
         });
@@ -85,7 +94,13 @@ class UserController extends Controller {
                 openApiService.validPath({
                     tags: ['Users'],
                     operationId: 'getProfile',
-                    responses: { 200: createResponseSchema('profileSchema') },
+                    summary: 'Get your own user profile',
+                    description:
+                        'Detailed information about the current user root role and project membership',
+                    responses: {
+                        200: createResponseSchema('profileSchema'),
+                        ...getStandardResponses(401),
+                    },
                 }),
             ],
         });
@@ -99,11 +114,19 @@ class UserController extends Controller {
                 openApiService.validPath({
                     tags: ['Users'],
                     operationId: 'changeMyPassword',
+                    summary: 'Change your own password',
+                    description:
+                        'Requires specifying old password and confirming new password',
                     requestBody: createRequestSchema('passwordSchema'),
                     responses: {
                         200: emptyResponse,
-                        400: { description: 'password mismatch' },
+                        400: {
-                        401: { description: 'incorrect old password' },
+                            description: 'Old and new password do not match',
+                        },
+                        401: {
+                            description:
+                                'Old password is incorrect or user is not authenticated',
+                        },
                     },
                 }),
             ],