From 7003351b35d0956b0268735168471e03bb536f9d Mon Sep 17 00:00:00 2001
From: Christopher Kolstad <chriswk@getunleash.ai>
Date: Mon, 12 Jun 2023 14:56:45 +0200
Subject: [PATCH] docs: Health check endpoint (#3959)

### What
Adds documentation for the health check endpoint.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
---
 src/lib/openapi/meta-schema-rules.test.ts                    | 2 --
 src/lib/openapi/spec/health-check-schema.ts                  | 5 +++++
 src/lib/routes/health-check.ts                               | 3 +++
 .../e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap   | 5 +++++
 4 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/lib/openapi/meta-schema-rules.test.ts b/src/lib/openapi/meta-schema-rules.test.ts
index 314861edfe..2e840daa24 100644
--- a/src/lib/openapi/meta-schema-rules.test.ts
+++ b/src/lib/openapi/meta-schema-rules.test.ts
@@ -112,7 +112,6 @@ const metaRules: Rule[] = [
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
-            'healthCheckSchema',
             'idSchema',
             'instanceAdminStatsSchema',
             'legalValueSchema',
@@ -217,7 +216,6 @@ const metaRules: Rule[] = [
             'groupSchema',
             'groupsSchema',
             'groupUserModelSchema',
-            'healthCheckSchema',
             'idSchema',
             'instanceAdminStatsSchema',
             'legalValueSchema',
diff --git a/src/lib/openapi/spec/health-check-schema.ts b/src/lib/openapi/spec/health-check-schema.ts
index 19f1272338..a090cd22d5 100644
--- a/src/lib/openapi/spec/health-check-schema.ts
+++ b/src/lib/openapi/spec/health-check-schema.ts
@@ -3,12 +3,17 @@ import { FromSchema } from 'json-schema-to-ts';
 export const healthCheckSchema = {
     $id: '#/components/schemas/healthCheckSchema',
     type: 'object',
+    description:
+        'Used by service orchestrators to decide whether this Unleash instance should be marked as healthy or unhealthy',
     additionalProperties: false,
     required: ['health'],
     properties: {
         health: {
+            description:
+                'The state this Unleash instance is in. GOOD if everything is ok, BAD if the instance should be restarted',
             type: 'string',
             enum: ['GOOD', 'BAD'],
+            example: 'GOOD',
         },
     },
     components: {},
diff --git a/src/lib/routes/health-check.ts b/src/lib/routes/health-check.ts
index f7d148a822..440babafa7 100644
--- a/src/lib/routes/health-check.ts
+++ b/src/lib/routes/health-check.ts
@@ -31,6 +31,9 @@ export class HealthCheckController extends Controller {
                 openApiService.validPath({
                     tags: ['Operational'],
                     operationId: 'getHealth',
+                    summary: 'Get instance operational status',
+                    description:
+                        'This operation returns information about whether this Unleash instance is healthy and ready to serve requests or not. Typically used by your deployment orchestrator (e.g. Kubernetes, Docker Swarm, Mesos, et al.).',
                     responses: {
                         200: createResponseSchema('healthCheckSchema'),
                         500: createResponseSchema('healthCheckSchema'),
diff --git a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap b/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
index 33461af429..8cd1895cb5 100644
--- a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
+++ b/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
@@ -2737,12 +2737,15 @@ The provider you choose for your addon dictates what properties the \`parameters
       },
       "healthCheckSchema": {
         "additionalProperties": false,
+        "description": "Used by service orchestrators to decide whether this Unleash instance should be marked as healthy or unhealthy",
         "properties": {
           "health": {
+            "description": "The state this Unleash instance is in. GOOD if everything is ok, BAD if the instance should be restarted",
             "enum": [
               "GOOD",
               "BAD",
             ],
+            "example": "GOOD",
             "type": "string",
           },
         },
@@ -13726,6 +13729,7 @@ If the provided project does not exist, the list of events will be empty.",
     },
     "/health": {
       "get": {
+        "description": "This operation returns information about whether this Unleash instance is healthy and ready to serve requests or not. Typically used by your deployment orchestrator (e.g. Kubernetes, Docker Swarm, Mesos, et al.).",
         "operationId": "getHealth",
         "responses": {
           "200": {
@@ -13749,6 +13753,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "healthCheckSchema",
           },
         },
+        "summary": "Get instance operational status",
         "tags": [
           "Operational",
         ],