feat: Maintenance openapi (#3478)

src/lib/openapi/index.ts

@@ -140,6 +140,7 @@ import { openApiTags } from './util';
 import { URL } from 'url';
 import apiVersion from '../util/version';
 import { maintenanceSchema } from './spec/maintenance-schema';
+import { toggleMaintenanceSchema } from './spec/toggle-maintenance-schema';
 import { bulkRegistrationSchema } from './spec/bulk-registration-schema';
 import { bulkMetricsSchema } from './spec/bulk-metrics-schema';
 import { clientMetricsEnvSchema } from './spec/client-metrics-env-schema';
@@ -213,6 +214,7 @@ export const schemas = {
     legalValueSchema,
     loginSchema,
     maintenanceSchema,
+    toggleMaintenanceSchema,
     meSchema,
     nameSchema,
     overrideSchema,

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

@@ -8,6 +8,7 @@ export const maintenanceSchema = {
     properties: {
         enabled: {
             type: 'boolean',
+            example: true,
         },
     },
     components: {},

src/lib/openapi/spec/toggle-maintenance-schema.ts

@@ -0,0 +1,18 @@
+import { FromSchema } from 'json-schema-to-ts';
+
+export const toggleMaintenanceSchema = {
+    $id: '#/components/schemas/toggleMaintenanceSchema',
+    type: 'object',
+    required: ['enabled'],
+    properties: {
+        enabled: {
+            type: 'boolean',
+            example: true,
+        },
+    },
+    components: {},
+} as const;
+
+export type ToggleMaintenanceSchema = FromSchema<
+    typeof toggleMaintenanceSchema
+>;

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

@@ -6,6 +6,7 @@ import {
     createRequestSchema,
     createResponseSchema,
     emptyResponse,
+    getStandardResponses,
 } from '../../openapi';
 import { OpenApiService } from '../../services';
 import { IAuthRequest } from '../unleash-types';
@@ -41,12 +42,16 @@ export default class MaintenanceController extends Controller {
             handler: this.toggleMaintenance,
             middleware: [
                 this.openApiService.validPath({
+                    summary: 'Enabled/disabled maintenance mode',
+                    description:
+                        'Lets administrators put Unleash into a mostly read-only mode. While Unleash is in maintenance mode, users can not change any configuration settings',
                     tags: ['Maintenance'],
                     operationId: 'toggleMaintenance',
                     responses: {
                         204: emptyResponse,
+                        ...getStandardResponses(400, 401, 403),
                     },
-                    requestBody: createRequestSchema('maintenanceSchema'),
+                    requestBody: createRequestSchema('toggleMaintenanceSchema'),
                 }),
             ],
         });
@@ -57,10 +62,14 @@ export default class MaintenanceController extends Controller {
             handler: this.getMaintenance,
             middleware: [
                 this.openApiService.validPath({
+                    summary: 'Get maintenance mode status',
+                    description:
+                        'Tells you whether maintenance mode is enabled or disabled',
                     tags: ['Maintenance'],
                     operationId: 'getMaintenance',
                     responses: {
                         200: createResponseSchema('maintenanceSchema'),
+                        ...getStandardResponses(401, 403),
                     },
                 }),
             ],

src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap

@@ -2178,6 +2178,7 @@ exports[`should serve the OpenAPI spec 1`] = `
         "additionalProperties": false,
         "properties": {
           "enabled": {
+            "example": true,
             "type": "boolean",
           },
         },
@@ -3799,6 +3800,18 @@ Stats are divided into current and previous **windows**.
         ],
         "type": "object",
       },
+      "toggleMaintenanceSchema": {
+        "properties": {
+          "enabled": {
+            "example": true,
+            "type": "boolean",
+          },
+        },
+        "required": [
+          "enabled",
+        ],
+        "type": "object",
+      },
       "tokenUserSchema": {
         "additionalProperties": false,
         "properties": {
@@ -5821,6 +5834,7 @@ If the provided project does not exist, the list of events will be empty.",
     },
     "/api/admin/maintenance": {
       "get": {
+        "description": "Tells you whether maintenance mode is enabled or disabled",
         "operationId": "getMaintenance",
         "responses": {
           "200": {
@@ -5833,29 +5847,47 @@ If the provided project does not exist, the list of events will be empty.",
             },
             "description": "maintenanceSchema",
           },
+          "401": {
+            "description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
+          },
+          "403": {
+            "description": "User credentials are valid but does not have enough privileges to execute this operation",
+          },
         },
+        "summary": "Get maintenance mode status",
         "tags": [
           "Maintenance",
         ],
       },
       "post": {
+        "description": "Lets administrators put Unleash into a mostly read-only mode. While Unleash is in maintenance mode, users can not change any configuration settings",
         "operationId": "toggleMaintenance",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/maintenanceSchema",
+                "$ref": "#/components/schemas/toggleMaintenanceSchema",
               },
             },
           },
-          "description": "maintenanceSchema",
+          "description": "toggleMaintenanceSchema",
           "required": true,
         },
         "responses": {
           "204": {
             "description": "This response has no body.",
           },
+          "400": {
+            "description": "The request data does not match what we expect.",
+          },
+          "401": {
+            "description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
+          },
+          "403": {
+            "description": "User credentials are valid but does not have enough privileges to execute this operation",
+          },
         },
+        "summary": "Enabled/disabled maintenance mode",
         "tags": [
           "Maintenance",
         ],