OpenAPI: clean up remaining schemas, part 1 (#4351)

Part of linear task 1-1167. Fixes the first slew of schemas missing
descriptions/examples, etc.

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',

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',

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: {

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',

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: {

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: {},

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;