diff --git a/src/lib/openapi/meta-schema-rules.test.ts b/src/lib/openapi/meta-schema-rules.test.ts index 986c24c981..042baa430c 100644 --- a/src/lib/openapi/meta-schema-rules.test.ts +++ b/src/lib/openapi/meta-schema-rules.test.ts @@ -90,7 +90,6 @@ const metaRules: Rule[] = [ }, }, knownExceptions: [ - 'createInvitedUserSchema', 'featureStrategySegmentSchema', 'maintenanceSchema', 'toggleMaintenanceSchema', @@ -118,12 +117,6 @@ const metaRules: Rule[] = [ required: ['description'], }, knownExceptions: [ - 'adminFeaturesQuerySchema', - 'applicationSchema', - 'applicationsSchema', - 'createFeatureSchema', - 'createInvitedUserSchema', - 'dateSchema', 'featureStrategySegmentSchema', 'maintenanceSchema', 'toggleMaintenanceSchema', diff --git a/src/lib/openapi/spec/admin-features-query-schema.ts b/src/lib/openapi/spec/admin-features-query-schema.ts index c51fdbf727..954cd3d13c 100644 --- a/src/lib/openapi/spec/admin-features-query-schema.ts +++ b/src/lib/openapi/spec/admin-features-query-schema.ts @@ -4,6 +4,8 @@ export const adminFeaturesQuerySchema = { $id: '#/components/schemas/adminFeaturesQuerySchema', type: 'object', additionalProperties: false, + description: + 'Query parameters used to modify the list of features returned.', properties: { tag: { type: 'array', diff --git a/src/lib/openapi/spec/application-schema.ts b/src/lib/openapi/spec/application-schema.ts index 064f4aa58f..b58343a565 100644 --- a/src/lib/openapi/spec/application-schema.ts +++ b/src/lib/openapi/spec/application-schema.ts @@ -3,6 +3,8 @@ import { FromSchema } from 'json-schema-to-ts'; export const applicationSchema = { $id: '#/components/schemas/applicationSchema', type: 'object', + description: + "Data about an application that's connected to Unleash via an SDK.", additionalProperties: false, required: ['appName'], properties: { diff --git a/src/lib/openapi/spec/applications-schema.ts b/src/lib/openapi/spec/applications-schema.ts index 294a456161..21d293bc32 100644 --- a/src/lib/openapi/spec/applications-schema.ts +++ b/src/lib/openapi/spec/applications-schema.ts @@ -4,11 +4,13 @@ import { FromSchema } from 'json-schema-to-ts'; export const applicationsSchema = { $id: '#/components/schemas/applicationsSchema', additionalProperties: false, + description: + 'An object containing a list of applications that have connected to Unleash via an SDK.', type: 'object', properties: { applications: { description: - 'Contains a list of applications that have connected via an SDK', + 'The list of applications that have connected to this Unleash instance.', type: 'array', items: { $ref: '#/components/schemas/applicationSchema', diff --git a/src/lib/openapi/spec/create-feature-schema.ts b/src/lib/openapi/spec/create-feature-schema.ts index 96e5be61a8..73dc3f7f0f 100644 --- a/src/lib/openapi/spec/create-feature-schema.ts +++ b/src/lib/openapi/spec/create-feature-schema.ts @@ -3,6 +3,7 @@ import { FromSchema } from 'json-schema-to-ts'; export const createFeatureSchema = { $id: '#/components/schemas/createFeatureSchema', type: 'object', + description: 'Data used to create a new feature toggle.', required: ['name'], properties: { name: { diff --git a/src/lib/openapi/spec/create-invited-user-schema.ts b/src/lib/openapi/spec/create-invited-user-schema.ts index dd64ebcac3..33291dfb5f 100644 --- a/src/lib/openapi/spec/create-invited-user-schema.ts +++ b/src/lib/openapi/spec/create-invited-user-schema.ts @@ -5,18 +5,27 @@ export const createInvitedUserSchema = { type: 'object', additionalProperties: false, required: ['email', 'name', 'password'], + description: 'Data used to create a user that has been invited to Unleash.', properties: { username: { type: 'string', + description: "The user's username. Must be unique if provided.", + example: 'Hunter', }, email: { type: 'string', + description: "The invited user's email address", + example: 'hunter@example.com', }, name: { type: 'string', + description: "The user's name", + example: 'Hunter Burgan', }, password: { type: 'string', + description: "The user's password", + example: 'hunter2', }, }, components: {}, diff --git a/src/lib/openapi/spec/date-schema.ts b/src/lib/openapi/spec/date-schema.ts index 1c05696bd0..10c6dd62a0 100644 --- a/src/lib/openapi/spec/date-schema.ts +++ b/src/lib/openapi/spec/date-schema.ts @@ -2,7 +2,23 @@ import { FromSchema } from 'json-schema-to-ts'; export const dateSchema = { $id: '#/components/schemas/dateSchema', - oneOf: [{ type: 'string', format: 'date-time' }, { type: 'number' }], + description: + 'A representation of a date. Either as a date-time string or as a UNIX timestamp.', + oneOf: [ + { + type: 'string', + format: 'date-time', + description: + 'An [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339.html)-compliant timestamp.', + example: '2023-07-27T11:23:44Z', + }, + { + type: 'integer', + description: + 'A [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time).', + example: 1690449593, + }, + ], components: {}, } as const;