From ab2553175817ef59263ce93d5fa4e467b1404d2f Mon Sep 17 00:00:00 2001 From: gorkem-bwl Date: Mon, 19 Jan 2026 14:13:18 -0500 Subject: [PATCH] docs: fix OpenAPI spec accuracy and warnings ## Changes ### Route Corrections - Remove non-existent `/auth/refresh` endpoint - Add missing `/auth/users/{userId}/password` PUT endpoint - Fix `/notifications` GET -> `/notifications/team` GET (correct path) ### OpenAPI 3.1.0 Compliance - Fix `nullable` warnings by using `type: ["string", "null"]` syntax - Updated Incident schema nullable fields (endTime, message, statusCode, etc.) - Updated QueueJob schema nullable fields (processedOn, finishedOn) - Updated Check schema nullable field (ackAt) ### Verified Against Codebase - Audited all 76 API endpoints across 12 route files - Confirmed DELETE /checks/team and DELETE /checks/{monitorId} exist - All routes now match actual codebase implementation ## Validation - Passes `swagger-cli validate` - Only remaining warnings are cosmetic `example` deprecations --- server/openapi.json | 196 +++++++++++++++++++++++--------------------- 1 file changed, 101 insertions(+), 95 deletions(-) diff --git a/server/openapi.json b/server/openapi.json index d104501d0..d56c619bf 100644 --- a/server/openapi.json +++ b/server/openapi.json @@ -162,51 +162,6 @@ } } }, - "/auth/refresh": { - "post": { - "tags": ["auth"], - "summary": "Refresh access token", - "description": "Generate new access token using refresh token", - "parameters": [ - { - "name": "x-refresh-token", - "in": "header", - "description": "Refresh token", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "authorization", - "in": "header", - "description": "Bearer token (old access token)", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Token refreshed successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - } - } - }, "/auth/user/{userId}": { "put": { "tags": ["auth"], @@ -1362,6 +1317,39 @@ } }, "/notifications": { + "post": { + "tags": ["notifications"], + "summary": "Create notification", + "description": "Create a new notification integration", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateNotificationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Notification created successfully" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, + "/notifications/team": { "get": { "tags": ["notifications"], "summary": "Get team notifications", @@ -1401,37 +1389,6 @@ "bearerAuth": [] } ] - }, - "post": { - "tags": ["notifications"], - "summary": "Create notification", - "description": "Create a new notification integration", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateNotificationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Notification created successfully" - }, - "422": { - "$ref": "#/components/responses/ValidationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } - }, - "security": [ - { - "bearerAuth": [] - } - ] } }, "/notifications/{id}": { @@ -1822,6 +1779,64 @@ ] } }, + "/auth/users/{userId}/password": { + "put": { + "tags": ["auth"], + "summary": "Update user password by ID", + "description": "Update a specific user's password by ID (superadmin only)", + "parameters": [ + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["password"], + "properties": { + "password": { + "type": "string", + "format": "password", + "minLength": 8, + "description": "New password for the user" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + }, + "security": [ + { + "bearerAuth": [] + } + ] + } + }, "/invite": { "post": { "tags": ["invite"], @@ -4096,9 +4111,8 @@ "description": "When the incident started" }, "endTime": { - "type": "string", + "type": ["string", "null"], "format": "date-time", - "nullable": true, "description": "When the incident was resolved (null if ongoing)" }, "status": { @@ -4106,29 +4120,24 @@ "description": "Incident status (true = ongoing, false = resolved)" }, "message": { - "type": "string", - "nullable": true, + "type": ["string", "null"], "description": "Error message or description" }, "statusCode": { - "type": "integer", - "nullable": true, + "type": ["integer", "null"], "description": "HTTP status code if applicable" }, "resolutionType": { - "type": "string", - "enum": ["automatic", "manual"], - "nullable": true, + "type": ["string", "null"], + "enum": ["automatic", "manual", null], "description": "How the incident was resolved" }, "resolvedBy": { - "type": "string", - "nullable": true, + "type": ["string", "null"], "description": "User ID who resolved the incident (for manual resolution)" }, "comment": { - "type": "string", - "nullable": true, + "type": ["string", "null"], "description": "Resolution comment" }, "checks": { @@ -4220,15 +4229,13 @@ "description": "When the job was created" }, "processedOn": { - "type": "string", + "type": ["string", "null"], "format": "date-time", - "nullable": true, "description": "When the job started processing" }, "finishedOn": { - "type": "string", + "type": ["string", "null"], "format": "date-time", - "nullable": true, "description": "When the job finished" } } @@ -4358,9 +4365,8 @@ "description": "Whether the check has been acknowledged" }, "ackAt": { - "type": "string", + "type": ["string", "null"], "format": "date-time", - "nullable": true, "description": "When the check was acknowledged" }, "expiry": {