From 4ce78ccecd90161dc7bc44bf05ee076818342489 Mon Sep 17 00:00:00 2001 From: Christopher Kolstad Date: Mon, 10 Jul 2023 10:18:08 +0200 Subject: [PATCH] docs: add description to requests per seconds schemas (#4182) ### What Adds a quick and dirty description to requestPerSeconds and segmentedRequestPerSecondsSchema so the enterprise /rps endpoint has better API docs. --------- Co-authored-by: Simon Hornby --- src/lib/openapi/meta-schema-rules.test.ts | 3 -- .../spec/requests-per-second-schema.ts | 32 +++++++++++++++++-- .../requests-per-second-segmented-schema.ts | 1 + 3 files changed, 31 insertions(+), 5 deletions(-) diff --git a/src/lib/openapi/meta-schema-rules.test.ts b/src/lib/openapi/meta-schema-rules.test.ts index ea3b2e1f5c..9ff8ddb860 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[] = [ 'projectsSchema', 'pushVariantsSchema', 'resetPasswordSchema', - 'requestsPerSecondSchema', 'sdkContextSchema', 'setUiConfigSchema', 'splashSchema', @@ -169,8 +168,6 @@ const metaRules: Rule[] = [ 'playgroundStrategySchema', 'pushVariantsSchema', 'resetPasswordSchema', - 'requestsPerSecondSchema', - 'requestsPerSecondSegmentedSchema', 'setStrategySortOrderSchema', 'setUiConfigSchema', 'sortOrderSchema', diff --git a/src/lib/openapi/spec/requests-per-second-schema.ts b/src/lib/openapi/spec/requests-per-second-schema.ts index 66ad039f92..1e4d868dca 100644 --- a/src/lib/openapi/spec/requests-per-second-schema.ts +++ b/src/lib/openapi/spec/requests-per-second-schema.ts @@ -3,15 +3,25 @@ import { FromSchema } from 'json-schema-to-ts'; export const requestsPerSecondSchema = { $id: '#/components/schemas/requestsPerSecondSchema', type: 'object', + description: + 'Statistics for usage of Unleash, formatted so it can easily be used in a graph', properties: { status: { type: 'string', + description: + 'Whether the query against prometheus succeeded or failed', + enum: ['success', 'failure'], + example: 'success', }, data: { type: 'object', + description: 'The query result from prometheus', properties: { resultType: { type: 'string', + description: 'Prometheus compatible result type.', + enum: ['matrix', 'vector', 'scalar', 'string'], + example: 'vector', }, result: { description: @@ -19,6 +29,8 @@ export const requestsPerSecondSchema = { type: 'array', items: { type: 'object', + description: + 'A representation of a single metric to build a line in a graph', properties: { metric: { description: @@ -26,10 +38,16 @@ export const requestsPerSecondSchema = { type: 'object', properties: { appName: { + description: + 'Name of the application this metric relates to', type: 'string', + example: 'mySdk', }, endpoint: { + description: + 'Which endpoint has been accessed', type: 'string', + example: '/api/frontend', }, }, }, @@ -39,10 +57,20 @@ export const requestsPerSecondSchema = { type: 'array', items: { type: 'array', + description: + 'Either the x axis represented as a number or the y axis represented as a string', items: { anyOf: [ - { type: 'string' }, - { type: 'number' }, + { + type: 'string', + description: + 'An identifier for the line in the graph', + }, + { + type: 'number', + description: + 'The number of requests at this point in time', + }, ], }, }, diff --git a/src/lib/openapi/spec/requests-per-second-segmented-schema.ts b/src/lib/openapi/spec/requests-per-second-segmented-schema.ts index 9767a2404d..252d74b3c7 100644 --- a/src/lib/openapi/spec/requests-per-second-segmented-schema.ts +++ b/src/lib/openapi/spec/requests-per-second-segmented-schema.ts @@ -3,6 +3,7 @@ import { requestsPerSecondSchema } from './requests-per-second-schema'; export const requestsPerSecondSegmentedSchema = { $id: '#/components/schemas/requestsPerSecondSegmentedSchema', type: 'object', + description: 'Get usage metrics separated by client and admin paths', properties: { clientMetrics: { $ref: '#/components/schemas/requestsPerSecondSchema',