chore: amend open api tags descriptions and examples (#3519)

## About the changes
Adds descriptions and examples to tag schemas

src/lib/openapi/meta-schema-rules.test.ts

@@ -92,7 +92,6 @@ const metaRules: Rule[] = [
             'featuresSchema',
             'featureStrategySchema',
             'featureStrategySegmentSchema',
-            'featureTagSchema',
             'featureTypeSchema',
             'featureTypesSchema',
             'featureUsageSchema',
@@ -144,9 +143,6 @@ const metaRules: Rule[] = [
             'stateSchema',
             'strategiesSchema',
             'strategySchema',
-            'tagsBulkAddSchema',
-            'tagSchema',
-            'tagsSchema',
             'tagTypeSchema',
             'tagTypesSchema',
             'tagWithVersionSchema',
@@ -157,7 +153,6 @@ const metaRules: Rule[] = [
             'updateFeatureStrategySchema',
             'updateTagTypeSchema',
             'updateUserSchema',
-            'updateTagsSchema',
             'upsertContextFieldSchema',
             'upsertSegmentSchema',
             'upsertStrategySchema',

src/lib/openapi/spec/feature-tag-schema.ts

@@ -3,23 +3,36 @@ import { FromSchema } from 'json-schema-to-ts';
 export const featureTagSchema = {
     $id: '#/components/schemas/featureTagSchema',
     type: 'object',
+    description: 'Describes a tag applied to a feature',
     additionalProperties: false,
     required: ['featureName', 'tagValue'],
     properties: {
         featureName: {
             type: 'string',
+            example: 'my-feature',
+            description: 'The name of the feature this tag is applied to',
         },
         tagType: {
             type: 'string',
+            example: 'simple',
+            description: 'The type of tag',
         },
         tagValue: {
             type: 'string',
+            example: 'my-tag',
+            description: 'The value of the tag',
         },
         type: {
+            deprecated: true,
             type: 'string',
+            description:
+                'This field is deprecated and currently unused, use tagType instead',
         },
         value: {
+            deprecated: true,
             type: 'string',
+            description:
+                'This field is deprecated and currently unused, use tagValue instead',
         },
     },
     components: {},

src/lib/openapi/spec/tag-schema.ts

@@ -5,6 +5,7 @@ export const TAG_MAX_LENGTH = 50;
 export const tagSchema = {
     $id: '#/components/schemas/tagSchema',
     type: 'object',
+    description: 'Representation of a tag',
     additionalProperties: false,
     required: ['value', 'type'],
     properties: {
@@ -12,18 +13,18 @@ export const tagSchema = {
             type: 'string',
             minLength: TAG_MIN_LENGTH,
             maxLength: TAG_MAX_LENGTH,
+            description: 'The value of the tag',
+            example: 'a-tag-value',
         },
         type: {
             type: 'string',
             minLength: TAG_MIN_LENGTH,
             maxLength: TAG_MAX_LENGTH,
             default: 'simple',
+            description: 'The type of the tag',
+            example: 'simple',
         },
     },
-    example: {
-        value: 'tag-value',
-        type: 'simple',
-    },
     components: {},
 } as const;
 

src/lib/openapi/spec/tags-bulk-add-schema.ts

@@ -4,11 +4,14 @@ import { tagSchema } from './tag-schema';
 
 export const tagsBulkAddSchema = {
     $id: '#/components/schemas/tagsBulkAddSchema',
+    description: 'Represents tag changes to be applied to a list of features.',
     type: 'object',
     additionalProperties: false,
     required: ['features', 'tags'],
     properties: {
         features: {
+            description:
+                'The list of features that will be affected by the tag changes.',
             type: 'array',
             items: {
                 type: 'string',
@@ -16,6 +19,7 @@ export const tagsBulkAddSchema = {
             },
         },
         tags: {
+            description: 'The tag changes to be applied to the features.',
             $ref: '#/components/schemas/updateTagsSchema',
         },
     },

src/lib/openapi/spec/tags-schema.ts

@@ -3,15 +3,18 @@ import { tagSchema } from './tag-schema';
 
 export const tagsSchema = {
     $id: '#/components/schemas/tagsSchema',
+    description: 'A list of tags with a version number',
     type: 'object',
     additionalProperties: false,
     required: ['version', 'tags'],
     properties: {
         version: {
             type: 'integer',
+            description: 'The version of the schema used to model the tags.',
         },
         tags: {
             type: 'array',
+            description: 'A list of tags.',
             items: {
                 $ref: '#/components/schemas/tagSchema',
             },

src/lib/openapi/spec/update-tags-schema.ts

@@ -4,17 +4,20 @@ import { tagSchema } from './tag-schema';
 export const updateTagsSchema = {
     $id: '#/components/schemas/updateTagsSchema',
     type: 'object',
+    description: 'Represents a set of changes to tags of a feature.',
     additionalProperties: false,
     required: ['addedTags', 'removedTags'],
     properties: {
         addedTags: {
             type: 'array',
+            description: 'Tags to add to the feature.',
             items: {
                 $ref: '#/components/schemas/tagSchema',
             },
         },
         removedTags: {
             type: 'array',
+            description: 'Tags to remove from the feature.',
             items: {
                 $ref: '#/components/schemas/tagSchema',
             },

src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap

@@ -1618,20 +1618,31 @@ exports[`should serve the OpenAPI spec 1`] = `
       },
       "featureTagSchema": {
         "additionalProperties": false,
+        "description": "Describes a tag applied to a feature",
         "properties": {
           "featureName": {
+            "description": "The name of the feature this tag is applied to",
+            "example": "my-feature",
             "type": "string",
           },
           "tagType": {
+            "description": "The type of tag",
+            "example": "simple",
             "type": "string",
           },
           "tagValue": {
+            "description": "The value of the tag",
+            "example": "my-tag",
             "type": "string",
           },
           "type": {
+            "deprecated": true,
+            "description": "This field is deprecated and currently unused, use tagType instead",
             "type": "string",
           },
           "value": {
+            "deprecated": true,
+            "description": "This field is deprecated and currently unused, use tagValue instead",
             "type": "string",
           },
         },
@@ -3706,18 +3717,19 @@ Stats are divided into current and previous **windows**.
       },
       "tagSchema": {
         "additionalProperties": false,
-        "example": {
+        "description": "Representation of a tag",
-          "type": "simple",
-          "value": "tag-value",
-        },
         "properties": {
           "type": {
             "default": "simple",
+            "description": "The type of the tag",
+            "example": "simple",
             "maxLength": 50,
             "minLength": 2,
             "type": "string",
           },
           "value": {
+            "description": "The value of the tag",
+            "example": "a-tag-value",
             "maxLength": 50,
             "minLength": 2,
             "type": "string",
@@ -3785,8 +3797,10 @@ Stats are divided into current and previous **windows**.
       },
       "tagsBulkAddSchema": {
         "additionalProperties": false,
+        "description": "Represents tag changes to be applied to a list of features.",
         "properties": {
           "features": {
+            "description": "The list of features that will be affected by the tag changes.",
             "items": {
               "minLength": 1,
               "type": "string",
@@ -3795,6 +3809,7 @@ Stats are divided into current and previous **windows**.
           },
           "tags": {
             "$ref": "#/components/schemas/updateTagsSchema",
+            "description": "The tag changes to be applied to the features.",
           },
         },
         "required": [
@@ -3805,14 +3820,17 @@ Stats are divided into current and previous **windows**.
       },
       "tagsSchema": {
         "additionalProperties": false,
+        "description": "A list of tags with a version number",
         "properties": {
           "tags": {
+            "description": "A list of tags.",
             "items": {
               "$ref": "#/components/schemas/tagSchema",
             },
             "type": "array",
           },
           "version": {
+            "description": "The version of the schema used to model the tags.",
             "type": "integer",
           },
         },
@@ -4028,6 +4046,7 @@ Stats are divided into current and previous **windows**.
       },
       "updateTagsSchema": {
         "additionalProperties": false,
+        "description": "Represents a set of changes to tags of a feature.",
         "example": {
           "addedTags": [
             {
@@ -4044,12 +4063,14 @@ Stats are divided into current and previous **windows**.
         },
         "properties": {
           "addedTags": {
+            "description": "Tags to add to the feature.",
             "items": {
               "$ref": "#/components/schemas/tagSchema",
             },
             "type": "array",
           },
           "removedTags": {
+            "description": "Tags to remove from the feature.",
             "items": {
               "$ref": "#/components/schemas/tagSchema",
             },