From b3e98ac95dafe5f11b2f3ffac0ea25463c97006f Mon Sep 17 00:00:00 2001 From: Alex Holliday Date: Tue, 25 Aug 2026 11:14:50 -0700 Subject: [PATCH] update openapi docs --- server/openapi.json | 1034 ++++++++++++++++++++++++++++++ server/openapi/index.ts | 2 + server/openapi/routes/proxies.ts | 75 +++ 3 files changed, 1111 insertions(+) create mode 100644 server/openapi/routes/proxies.ts diff --git a/server/openapi.json b/server/openapi.json index 759fca9d7..c2408b580 100644 --- a/server/openapi.json +++ b/server/openapi.json @@ -48,6 +48,10 @@ "name": "settings", "description": "Global application settings (admin/superadmin)." }, + { + "name": "proxies", + "description": "Outbound proxy servers for routing HTTP monitor checks, team-scoped with an instance-wide admin listing." + }, { "name": "invite", "description": "Team invitations and accepting them." @@ -373,6 +377,13 @@ "ignoreTlsErrors": { "type": "boolean" }, + "proxyMode": { + "type": "string", + "enum": ["inherit", "none", "custom"] + }, + "proxyId": { + "type": "string" + }, "useAdvancedMatching": { "type": "boolean" }, @@ -486,6 +497,7 @@ "statusWindowSize", "statusWindowThreshold", "ignoreTlsErrors", + "proxyMode", "useAdvancedMatching", "method", "notifications", @@ -580,6 +592,13 @@ "ignoreTlsErrors": { "type": "boolean" }, + "proxyMode": { + "type": "string", + "enum": ["inherit", "none", "custom"] + }, + "proxyId": { + "type": "string" + }, "useAdvancedMatching": { "type": "boolean" }, @@ -695,6 +714,7 @@ "statusWindowSize", "statusWindowThreshold", "ignoreTlsErrors", + "proxyMode", "useAdvancedMatching", "method", "notifications", @@ -7785,6 +7805,14 @@ "type": "boolean", "default": false }, + "proxyMode": { + "type": "string", + "enum": ["inherit", "none", "custom"], + "default": "inherit" + }, + "proxyId": { + "type": "string" + }, "useAdvancedMatching": { "type": "boolean", "default": false @@ -8432,6 +8460,14 @@ "type": "boolean", "default": false }, + "proxyMode": { + "type": "string", + "enum": ["inherit", "none", "custom"], + "default": "inherit" + }, + "proxyId": { + "type": "string" + }, "useAdvancedMatching": { "type": "boolean", "default": false @@ -9050,6 +9086,13 @@ "ignoreTlsErrors": { "type": "boolean" }, + "proxyMode": { + "type": "string", + "enum": ["inherit", "none", "custom"] + }, + "proxyId": { + "type": "string" + }, "useAdvancedMatching": { "type": "boolean" }, @@ -10210,6 +10253,990 @@ } } }, + "/proxies": { + "post": { + "tags": ["proxies"], + "summary": "Create a proxy for the caller's team", + "security": [ + { + "bearerAuth": [] + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string", + "minLength": 1 + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535 + }, + "username": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "required": ["name", "protocol", "host", "port"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + }, + "get": { + "tags": ["proxies"], + "summary": "List all proxies on the instance (admin/superadmin)", + "security": [ + { + "bearerAuth": [] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + } + }, + "/proxies/team": { + "get": { + "tags": ["proxies"], + "summary": "List proxies for the caller's team", + "security": [ + { + "bearerAuth": [] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + } + }, + "/proxies/{id}": { + "get": { + "tags": ["proxies"], + "summary": "Get a proxy by id", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1 + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + }, + "patch": { + "tags": ["proxies"], + "summary": "Edit a proxy", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1 + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string", + "minLength": 1 + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535 + }, + "username": { + "type": "string" + }, + "password": { + "type": "string" + }, + "clearPassword": { + "type": "boolean" + }, + "clearUsername": { + "type": "boolean" + } + }, + "required": ["name", "protocol", "host", "port"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + }, + "delete": { + "tags": ["proxies"], + "summary": "Delete a proxy", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1 + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [true] + }, + "msg": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "teamId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string", + "enum": ["http", "https"] + }, + "host": { + "type": "string" + }, + "port": { + "type": "number" + }, + "username": { + "type": "string" + }, + "hasPassword": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": ["id", "teamId", "name", "protocol", "host", "port", "hasPassword", "createdAt", "updatedAt"], + "additionalProperties": { + "nullable": true + } + } + }, + "required": ["success", "msg", "data"] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "409": { + "description": "Proxy is in use by monitors or set as the global proxy", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "enum": [false] + }, + "msg": { + "type": "string" + }, + "data": { + "nullable": true + } + }, + "required": ["success", "msg"] + } + } + } + } + } + } + }, "/queue/jobs": { "get": { "tags": ["queue"], @@ -10839,6 +11866,13 @@ "maximum": 150 } } + }, + "globalProxyEnabled": { + "type": "boolean" + }, + "globalProxyId": { + "type": "string", + "nullable": true } } } diff --git a/server/openapi/index.ts b/server/openapi/index.ts index c96cec233..a50008a75 100644 --- a/server/openapi/index.ts +++ b/server/openapi/index.ts @@ -9,6 +9,7 @@ import "./routes/log.js"; import "./routes/maintenanceWindow.js"; import "./routes/monitor.js"; import "./routes/notification.js"; +import "./routes/proxies.js"; import "./routes/queue.js"; import "./routes/settings.js"; import "./routes/statusPage.js"; @@ -45,6 +46,7 @@ export function getOpenApiSpec(): JsonObject { { name: "maintenance-window", description: "Scheduled maintenance windows during which monitors do not generate incidents or alerts." }, { name: "status-page", description: "Public status pages, their configuration, and the monitors they expose." }, { name: "settings", description: "Global application settings (admin/superadmin)." }, + { name: "proxies", description: "Outbound proxy servers for routing HTTP monitor checks, team-scoped with an instance-wide admin listing." }, { name: "invite", description: "Team invitations and accepting them." }, { name: "queue", description: "Background job queue introspection and admin actions (admin/superadmin)." }, { name: "diagnostic", description: "System diagnostics for the running server (admin/superadmin)." }, diff --git a/server/openapi/routes/proxies.ts b/server/openapi/routes/proxies.ts new file mode 100644 index 000000000..0a742fcf1 --- /dev/null +++ b/server/openapi/routes/proxies.ts @@ -0,0 +1,75 @@ +import { z } from "zod"; +import { registry } from "../registry.js"; +import { bearer, json, okJson, errorEnvelope, standardErrors } from "../helpers.js"; +import { + createProxyBodyValidation, + editProxyBodyValidation, + getProxyByIdParamValidation, + editProxyParamValidation, + deleteProxyParamValidation, + proxyResponseSchema, +} from "@/api/validation/proxyValidation.js"; + +const tags = ["proxies"]; + +registry.registerPath({ + method: "post", + path: "/proxies", + tags, + summary: "Create a proxy for the caller's team", + security: bearer, + request: { body: { content: json(createProxyBodyValidation) } }, + responses: { "200": okJson(proxyResponseSchema), ...standardErrors }, +}); + +registry.registerPath({ + method: "get", + path: "/proxies", + tags, + summary: "List all proxies on the instance (admin/superadmin)", + security: bearer, + responses: { "200": okJson(z.array(proxyResponseSchema)), ...standardErrors }, +}); + +registry.registerPath({ + method: "get", + path: "/proxies/team", + tags, + summary: "List proxies for the caller's team", + security: bearer, + responses: { "200": okJson(z.array(proxyResponseSchema)), ...standardErrors }, +}); + +registry.registerPath({ + method: "get", + path: "/proxies/{id}", + tags, + summary: "Get a proxy by id", + security: bearer, + request: { params: getProxyByIdParamValidation }, + responses: { "200": okJson(proxyResponseSchema), ...standardErrors }, +}); + +registry.registerPath({ + method: "patch", + path: "/proxies/{id}", + tags, + summary: "Edit a proxy", + security: bearer, + request: { params: editProxyParamValidation, body: { content: json(editProxyBodyValidation) } }, + responses: { "200": okJson(proxyResponseSchema), ...standardErrors }, +}); + +registry.registerPath({ + method: "delete", + path: "/proxies/{id}", + tags, + summary: "Delete a proxy", + security: bearer, + request: { params: deleteProxyParamValidation }, + responses: { + "200": okJson(proxyResponseSchema), + "409": { description: "Proxy is in use by monitors or set as the global proxy", content: json(errorEnvelope) }, + ...standardErrors, + }, +});