From c1a1a0fdeb0055e06408f294aa17068292f75b88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gast=C3=B3n=20Fournier?= Date: Wed, 12 Apr 2023 11:29:51 +0200 Subject: [PATCH] docs: open api examples for segment schemas (#3503) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## About the changes Add additional documentation for segments --------- Co-authored-by: Nuno Góis --- src/lib/openapi/spec/constraint-schema.ts | 3 ++ src/lib/openapi/spec/segment-schema.ts | 2 ++ src/lib/openapi/spec/upsert-segment-schema.ts | 16 ++++++++++ .../__snapshots__/openapi.e2e.test.ts.snap | 30 +++++++++++++++++++ 4 files changed, 51 insertions(+) diff --git a/src/lib/openapi/spec/constraint-schema.ts b/src/lib/openapi/spec/constraint-schema.ts index 30d3b60bc9..58af9c407d 100644 --- a/src/lib/openapi/spec/constraint-schema.ts +++ b/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: {}, diff --git a/src/lib/openapi/spec/segment-schema.ts b/src/lib/openapi/spec/segment-schema.ts index 7962355317..15b8b4fe9a 100644 --- a/src/lib/openapi/spec/segment-schema.ts +++ b/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', }, diff --git a/src/lib/openapi/spec/upsert-segment-schema.ts b/src/lib/openapi/spec/upsert-segment-schema.ts index 6361fdd88c..f6d9765906 100644 --- a/src/lib/openapi/spec/upsert-segment-schema.ts +++ b/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, 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 index ae121e51ab..e34d979270 100644 --- a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap +++ b/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", },