From 89b619deba369ea6b7a81f6b1a809145cf6d9495 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.io>
Date: Fri, 4 Oct 2024 12:52:14 +0200
Subject: [PATCH] openapi: small adjustments to dashboard schemas (#8363)

This PR contains a number of small updates to the dashboard schemas,
including rewording descriptions, changing numbers to integers, setting
minimum values.
---
 ...rsonal-dashboard-project-details-schema.ts | 41 +++++++++++--------
 .../openapi/spec/personal-dashboard-schema.ts |  9 ++--
 2 files changed, 31 insertions(+), 19 deletions(-)

diff --git a/src/lib/openapi/spec/personal-dashboard-project-details-schema.ts b/src/lib/openapi/spec/personal-dashboard-project-details-schema.ts
index 74703fbc1c..35114079e1 100644
--- a/src/lib/openapi/spec/personal-dashboard-project-details-schema.ts
+++ b/src/lib/openapi/spec/personal-dashboard-project-details-schema.ts
@@ -17,7 +17,8 @@ export const personalDashboardProjectDetailsSchema = {
     properties: {
         insights: {
             type: 'object',
-            description: 'Insights for the project',
+            description:
+                'Insights for the project, including flag data and project health information.',
             additionalProperties: false,
             required: [
                 'avgHealthCurrentWindow',
@@ -30,44 +31,52 @@ export const personalDashboardProjectDetailsSchema = {
             ],
             properties: {
                 avgHealthCurrentWindow: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     description:
-                        'The average health score in the current window of the last 4 weeks',
+                        "The project's average health score over the last 4 weeks",
                     example: 80,
                     nullable: true,
                 },
                 avgHealthPastWindow: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     description:
-                        'The average health score in the previous 4 weeks before the current window',
+                        "The project's average health score over the previous 4-week window",
                     example: 70,
                     nullable: true,
                 },
                 totalFlags: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     example: 100,
-                    description: 'The current number of all flags',
+                    description: 'The current number of non-archived flags',
                 },
                 activeFlags: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     example: 98,
-                    description: 'The current number of active flags',
+                    description:
+                        'The number of active flags that are not stale or potentially stale',
                 },
                 staleFlags: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     example: 0,
                     description:
-                        'The current number of user marked stale flags',
+                        'The current number of flags that have been manually marked as stale',
                 },
                 potentiallyStaleFlags: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 0,
                     example: 2,
                     description:
-                        'The current number of time calculated potentially stale flags',
+                        'The number of potentially stale flags as calculated by Unleash',
                 },
                 health: {
-                    type: 'number',
-                    description: 'The current health score of the project',
+                    type: 'integer',
+                    minimum: 0,
+                    description: "The project's current health score",
                     example: 80,
                 },
             },
@@ -129,7 +138,7 @@ export const personalDashboardProjectDetailsSchema = {
                     },
                     type: {
                         type: 'string',
-                        enum: ['custom', 'project', 'root', 'custom-root'],
+                        enum: ['custom', 'project'],
                         example: 'project',
                         description: 'The type of the role',
                     },
diff --git a/src/lib/openapi/spec/personal-dashboard-schema.ts b/src/lib/openapi/spec/personal-dashboard-schema.ts
index 765750bc00..fe3717676f 100644
--- a/src/lib/openapi/spec/personal-dashboard-schema.ts
+++ b/src/lib/openapi/spec/personal-dashboard-schema.ts
@@ -99,19 +99,22 @@ export const personalDashboardSchema = {
                         description: 'The name of the project',
                     },
                     health: {
-                        type: 'number',
+                        type: 'integer',
                         example: 50,
+                        minimum: 0,
                         description:
                             "An indicator of the [project's health](https://docs.getunleash.io/reference/technical-debt#health-rating) on a scale from 0 to 100",
                     },
                     memberCount: {
-                        type: 'number',
+                        type: 'integer',
                         example: 4,
+                        minimum: 0,
                         description: 'The number of members this project has',
                     },
                     featureCount: {
-                        type: 'number',
+                        type: 'integer',
                         example: 10,
+                        minimum: 0,
                         description: 'The number of features this project has',
                     },
                 },