docs: improve open api (#3535)

## About the changes Amends based on #3519
Unleash · Apr 18, 2023 · 5940a81 · 5940a81
1 parent 7debbeb
commit 5940a81
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 12 deletions.
diff --git a/src/lib/openapi/spec/feature-tag-schema.ts b/src/lib/openapi/spec/feature-tag-schema.ts
@@ -15,7 +15,8 @@ export const featureTagSchema = {
         tagType: {
             type: 'string',
             example: 'simple',
-            description: 'The type of tag',
+            description:
+                'The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag',
         },
         tagValue: {
             type: 'string',
@@ -26,13 +27,13 @@ export const featureTagSchema = {
             deprecated: true,
             type: 'string',
             description:
-                'This field is deprecated and currently unused, use tagType instead',
+                'The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the `tagType` property.',
         },
         value: {
             deprecated: true,
             type: 'string',
             description:
-                'This field is deprecated and currently unused, use tagValue instead',
+                'The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the `tagValue` property.',
         },
     },
     components: {},

diff --git a/src/lib/openapi/spec/tag-schema.ts b/src/lib/openapi/spec/tag-schema.ts
@@ -5,7 +5,8 @@ export const TAG_MAX_LENGTH = 50;
 export const tagSchema = {
     $id: '#/components/schemas/tagSchema',
     type: 'object',
-    description: 'Representation of a tag',
+    description:
+        'Representation of a [tag](https://docs.getunleash.io/reference/tags)',
     additionalProperties: false,
     required: ['value', 'type'],
     properties: {
@@ -21,7 +22,8 @@ export const tagSchema = {
             minLength: TAG_MIN_LENGTH,
             maxLength: TAG_MAX_LENGTH,
             default: 'simple',
-            description: 'The type of the tag',
+            description:
+                'The [type](https://docs.getunleash.io/reference/tags#tag-types) of the tag',
             example: 'simple',
         },
     },

diff --git a/src/lib/openapi/spec/update-tags-schema.ts b/src/lib/openapi/spec/update-tags-schema.ts
@@ -4,7 +4,8 @@ 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.',
+    description:
+        "Represents a set of changes to a feature's tags, such as adding or removing tags.",
     additionalProperties: false,
     required: ['addedTags', 'removedTags'],
     properties: {

diff --git a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap b/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
@@ -1688,7 +1688,7 @@ exports[`should serve the OpenAPI spec 1`] = `
             "type": "string",
           },
           "tagType": {
-            "description": "The type of tag",
+            "description": "The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag",
             "example": "simple",
             "type": "string",
           },
@@ -1699,12 +1699,12 @@ exports[`should serve the OpenAPI spec 1`] = `
           },
           "type": {
             "deprecated": true,
-            "description": "This field is deprecated and currently unused, use tagType instead",
+            "description": "The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the \`tagType\` property.",
             "type": "string",
           },
           "value": {
             "deprecated": true,
-            "description": "This field is deprecated and currently unused, use tagValue instead",
+            "description": "The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the \`tagValue\` property.",
             "type": "string",
           },
         },
@@ -3785,11 +3785,11 @@ Stats are divided into current and previous **windows**.
       },
       "tagSchema": {
         "additionalProperties": false,
-        "description": "Representation of a tag",
+        "description": "Representation of a [tag](https://docs.getunleash.io/reference/tags)",
         "properties": {
           "type": {
             "default": "simple",
-            "description": "The type of the tag",
+            "description": "The [type](https://docs.getunleash.io/reference/tags#tag-types) of the tag",
             "example": "simple",
             "maxLength": 50,
             "minLength": 2,
@@ -4135,7 +4135,7 @@ Stats are divided into current and previous **windows**.
       },
       "updateTagsSchema": {
         "additionalProperties": false,
-        "description": "Represents a set of changes to tags of a feature.",
+        "description": "Represents a set of changes to a feature's tags, such as adding or removing tags.",
         "example": {
           "addedTags": [
             {