docs: open api examples for segment schemas (#3503)

## About the changes
Add additional documentation for segments

---------

Co-authored-by: Nuno Góis <github@nunogois.com>

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

@@ -18,6 +18,7 @@ export const constraintSchemaBase = {
                 'The operator to use when evaluating this constraint. For more information about the various operators, refer to [the strategy constraint operator documentation](https://docs.getunleash.io/reference/strategy-constraints#strategy-constraint-operators).',
             type: 'string',
             enum: ALL_OPERATORS,
+            example: 'IN',
         },
         caseInsensitive: {
             description:
@@ -38,11 +39,13 @@ export const constraintSchemaBase = {
             items: {
                 type: 'string',
             },
+            example: ['my-app', 'my-other-app'],
         },
         value: {
             description:
                 'The context value that should be used for constraint evaluation. Use this property instead of `values` for properties that only accept single values.',
             type: 'string',
+            example: 'my-app',
         },
     },
     components: {},

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

@@ -19,6 +19,8 @@ export const segmentSchema = {
         },
         constraints: {
             type: 'array',
+            description:
+                'List of constraints that determine which users are part of the segment',
             items: {
                 $ref: '#/components/schemas/constraintSchema',
             },

src/lib/openapi/spec/upsert-segment-schema.ts

@@ -16,14 +16,30 @@ export const upsertSegmentSchema = {
         project: {
             type: 'string',
             nullable: true,
+            description:
+                'Project from where this segment will be accessible. If none is defined the segment will be global (i.e. accessible from any project).',
         },
         constraints: {
             type: 'array',
+            description:
+                'List of constraints that determine which users will be part of the segment',
             items: {
                 $ref: '#/components/schemas/constraintSchema',
             },
         },
     },
+    example: {
+        name: 'segment name',
+        description: 'segment description',
+        project: 'optional project id',
+        constraints: [
+            {
+                contextName: 'environment',
+                operator: 'IN',
+                values: ['production', 'staging'],
+            },
+        ],
+    },
     components: {
         schemas: {
             constraintSchema,

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

@@ -761,14 +761,20 @@ exports[`should serve the OpenAPI spec 1`] = `
               "SEMVER_GT",
               "SEMVER_LT",
             ],
+            "example": "IN",
             "type": "string",
           },
           "value": {
             "description": "The context value that should be used for constraint evaluation. Use this property instead of \`values\` for properties that only accept single values.",
+            "example": "my-app",
             "type": "string",
           },
           "values": {
             "description": "The context values that should be used for constraint evaluation. Use this property instead of \`value\` for properties that accept multiple values.",
+            "example": [
+              "my-app",
+              "my-other-app",
+            ],
             "items": {
               "type": "string",
             },
@@ -2397,6 +2403,7 @@ exports[`should serve the OpenAPI spec 1`] = `
               "SEMVER_GT",
               "SEMVER_LT",
             ],
+            "example": "IN",
             "type": "string",
           },
           "result": {
@@ -2405,10 +2412,15 @@ exports[`should serve the OpenAPI spec 1`] = `
           },
           "value": {
             "description": "The context value that should be used for constraint evaluation. Use this property instead of \`values\` for properties that only accept single values.",
+            "example": "my-app",
             "type": "string",
           },
           "values": {
             "description": "The context values that should be used for constraint evaluation. Use this property instead of \`value\` for properties that accept multiple values.",
+            "example": [
+              "my-app",
+              "my-other-app",
+            ],
             "items": {
               "type": "string",
             },
@@ -3455,6 +3467,7 @@ Stats are divided into current and previous **windows**.
         "additionalProperties": false,
         "properties": {
           "constraints": {
+            "description": "List of constraints that determine which users are part of the segment",
             "items": {
               "$ref": "#/components/schemas/constraintSchema",
             },
@@ -4068,8 +4081,24 @@ Stats are divided into current and previous **windows**.
         "type": "object",
       },
       "upsertSegmentSchema": {
+        "example": {
+          "constraints": [
+            {
+              "contextName": "environment",
+              "operator": "IN",
+              "values": [
+                "production",
+                "staging",
+              ],
+            },
+          ],
+          "description": "segment description",
+          "name": "segment name",
+          "project": "optional project id",
+        },
         "properties": {
           "constraints": {
+            "description": "List of constraints that determine which users will be part of the segment",
             "items": {
               "$ref": "#/components/schemas/constraintSchema",
             },
@@ -4083,6 +4112,7 @@ Stats are divided into current and previous **windows**.
             "type": "string",
           },
           "project": {
+            "description": "Project from where this segment will be accessible. If none is defined the segment will be global (i.e. accessible from any project).",
             "nullable": true,
             "type": "string",
           },