From e4cbd9f8fe5e0508717d54271c9de96a05cba055 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 2 Aug 2023 13:51:16 +0200 Subject: [PATCH] [DOCS] Adds descriptions for Enrich APIs (#2215) --- output/schema/schema.json | 41 +++++++++++-------- .../DeleteEnrichPolicyRequest.ts | 4 ++ .../ExecuteEnrichPolicyRequest.ts | 9 ++++ .../get_policy/GetEnrichPolicyRequest.ts | 5 +++ .../put_policy/PutEnrichPolicyRequest.ts | 14 +++++++ .../enrich/stats/EnrichStatsRequest.ts | 1 + .../enrich/stats/EnrichStatsResponse.ts | 7 ++++ 7 files changed, 65 insertions(+), 16 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 56cfd00f75..3fd22b2d23 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -3455,7 +3455,8 @@ } }, "description": "Creates the enrich index for an existing enrich policy.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/execute-enrich-policy-api.html", + "docId": "execute-enrich-policy-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/execute-enrich-policy-api.html", "name": "enrich.execute_policy", "request": { "name": "Request", @@ -3537,7 +3538,8 @@ } }, "description": "Creates a new enrich policy.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/put-enrich-policy-api.html", + "docId": "put-enrich-policy-api", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-enrich-policy-api.html", "name": "enrich.put_policy", "request": { "name": "Request", @@ -102410,7 +102412,7 @@ }, "path": [ { - "description": "The name of the enrich policy", + "description": "Enrich policy to delete.", "name": "name", "required": true, "type": { @@ -102423,7 +102425,7 @@ } ], "query": [], - "specLocation": "enrich/delete_policy/DeleteEnrichPolicyRequest.ts#L23-L32" + "specLocation": "enrich/delete_policy/DeleteEnrichPolicyRequest.ts#L23-L36" }, { "body": { @@ -102507,7 +102509,7 @@ }, "path": [ { - "description": "The name of the enrich policy", + "description": "Enrich policy to execute.", "name": "name", "required": true, "type": { @@ -102521,9 +102523,10 @@ ], "query": [ { - "description": "Should the request should block until the execution is complete.", + "description": "If `true`, the request blocks other enrich policy execution requests until complete.", "name": "wait_for_completion", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -102533,7 +102536,7 @@ } } ], - "specLocation": "enrich/execute_policy/ExecuteEnrichPolicyRequest.ts#L23-L35" + "specLocation": "enrich/execute_policy/ExecuteEnrichPolicyRequest.ts#L23-L44" }, { "body": { @@ -102577,7 +102580,7 @@ "body": { "kind": "no_body" }, - "description": "Gets information about an enrich policy.", + "description": "Returns information about an enrich policy.", "inherits": { "type": { "name": "RequestBase", @@ -102591,7 +102594,7 @@ }, "path": [ { - "description": "A comma-separated list of enrich policy names", + "description": "Comma-separated list of enrich policy names used to limit the request.\nTo return information for all enrich policies, omit this parameter.", "name": "name", "required": false, "type": { @@ -102604,7 +102607,7 @@ } ], "query": [], - "specLocation": "enrich/get_policy/GetEnrichPolicyRequest.ts#L23-L32" + "specLocation": "enrich/get_policy/GetEnrichPolicyRequest.ts#L23-L37" }, { "body": { @@ -102641,6 +102644,7 @@ "kind": "properties", "properties": [ { + "description": "Matches enrich data to incoming documents based on a `geo_shape` query.", "name": "geo_match", "required": false, "type": { @@ -102652,6 +102656,7 @@ } }, { + "description": "Matches enrich data to incoming documents based on a `term` query.", "name": "match", "required": false, "type": { @@ -102663,6 +102668,7 @@ } }, { + "description": "Matches a number, date, or IP address in incoming documents to a range in the enrich index based on a `term` query.", "name": "range", "required": false, "type": { @@ -102675,7 +102681,7 @@ } ] }, - "description": "Creates a new enrich policy.", + "description": "Creates an enrich policy.", "inherits": { "type": { "name": "RequestBase", @@ -102689,7 +102695,7 @@ }, "path": [ { - "description": "The name of the enrich policy", + "description": "Name of the enrich policy to create or update.", "name": "name", "required": true, "type": { @@ -102702,7 +102708,7 @@ } ], "query": [], - "specLocation": "enrich/put_policy/PutEnrichPolicyRequest.ts#L24-L38" + "specLocation": "enrich/put_policy/PutEnrichPolicyRequest.ts#L24-L52" }, { "body": { @@ -102891,7 +102897,7 @@ "body": { "kind": "no_body" }, - "description": "Gets enrich coordinator statistics and information about enrich policies that are currently executing.", + "description": "Returns enrich coordinator statistics and information about enrich policies that are currently executing.", "inherits": { "type": { "name": "RequestBase", @@ -102905,13 +102911,14 @@ }, "path": [], "query": [], - "specLocation": "enrich/stats/EnrichStatsRequest.ts#L22-L27" + "specLocation": "enrich/stats/EnrichStatsRequest.ts#L22-L28" }, { "body": { "kind": "properties", "properties": [ { + "description": "Objects containing information about each coordinating ingest node for configured enrich processors.", "name": "coordinator_stats", "required": true, "type": { @@ -102926,6 +102933,7 @@ } }, { + "description": "Objects containing information about each enrich policy that is currently executing.", "name": "executing_policies", "required": true, "type": { @@ -102946,6 +102954,7 @@ "since": "7.16.0" } }, + "description": "Objects containing information about the enrich cache stats on each ingest node.", "name": "cache_stats", "required": false, "since": "7.16.0", @@ -102967,7 +102976,7 @@ "name": "Response", "namespace": "enrich.stats" }, - "specLocation": "enrich/stats/EnrichStatsResponse.ts#L22-L32" + "specLocation": "enrich/stats/EnrichStatsResponse.ts#L22-L39" }, { "generics": [ diff --git a/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts b/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts index 18c2ee877f..8b837981b3 100644 --- a/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts +++ b/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts @@ -21,12 +21,16 @@ import { RequestBase } from '@_types/Base' import { Name } from '@_types/common' /** + * Deletes an existing enrich policy and its enrich index. * @rest_spec_name enrich.delete_policy * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=public */ export interface Request extends RequestBase { path_parts: { + /** + * Enrich policy to delete. + */ name: Name } } diff --git a/specification/enrich/execute_policy/ExecuteEnrichPolicyRequest.ts b/specification/enrich/execute_policy/ExecuteEnrichPolicyRequest.ts index a9cc71fe04..c4149f7196 100644 --- a/specification/enrich/execute_policy/ExecuteEnrichPolicyRequest.ts +++ b/specification/enrich/execute_policy/ExecuteEnrichPolicyRequest.ts @@ -21,15 +21,24 @@ import { RequestBase } from '@_types/Base' import { Name } from '@_types/common' /** + * Creates the enrich index for an existing enrich policy. + * @doc_id execute-enrich-policy-api * @rest_spec_name enrich.execute_policy * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=public */ export interface Request extends RequestBase { path_parts: { + /** + * Enrich policy to execute. + */ name: Name } query_parameters: { + /** + * If `true`, the request blocks other enrich policy execution requests until complete. + * @server_default true + */ wait_for_completion?: boolean } } diff --git a/specification/enrich/get_policy/GetEnrichPolicyRequest.ts b/specification/enrich/get_policy/GetEnrichPolicyRequest.ts index 6f0f8c71e0..b6a1a5d301 100644 --- a/specification/enrich/get_policy/GetEnrichPolicyRequest.ts +++ b/specification/enrich/get_policy/GetEnrichPolicyRequest.ts @@ -21,12 +21,17 @@ import { RequestBase } from '@_types/Base' import { Names } from '@_types/common' /** + * Returns information about an enrich policy. * @rest_spec_name enrich.get_policy * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=public */ export interface Request extends RequestBase { path_parts: { + /** + * Comma-separated list of enrich policy names used to limit the request. + * To return information for all enrich policies, omit this parameter. + */ name?: Names } } diff --git a/specification/enrich/put_policy/PutEnrichPolicyRequest.ts b/specification/enrich/put_policy/PutEnrichPolicyRequest.ts index 10a18025b8..6c2aacae88 100644 --- a/specification/enrich/put_policy/PutEnrichPolicyRequest.ts +++ b/specification/enrich/put_policy/PutEnrichPolicyRequest.ts @@ -22,17 +22,31 @@ import { RequestBase } from '@_types/Base' import { Name } from '@_types/common' /** + * Creates an enrich policy. + * @doc_id put-enrich-policy-api * @rest_spec_name enrich.put_policy * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=public */ export interface Request extends RequestBase { path_parts: { + /** + * Name of the enrich policy to create or update. + */ name: Name } body: { + /** + * Matches enrich data to incoming documents based on a `geo_shape` query. + */ geo_match?: Policy + /** + * Matches enrich data to incoming documents based on a `term` query. + */ match?: Policy + /** + * Matches a number, date, or IP address in incoming documents to a range in the enrich index based on a `term` query. + */ range?: Policy } } diff --git a/specification/enrich/stats/EnrichStatsRequest.ts b/specification/enrich/stats/EnrichStatsRequest.ts index 3a56f903ea..6d63db512e 100644 --- a/specification/enrich/stats/EnrichStatsRequest.ts +++ b/specification/enrich/stats/EnrichStatsRequest.ts @@ -20,6 +20,7 @@ import { RequestBase } from '@_types/Base' /** + * Returns enrich coordinator statistics and information about enrich policies that are currently executing. * @rest_spec_name enrich.stats * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/enrich/stats/EnrichStatsResponse.ts b/specification/enrich/stats/EnrichStatsResponse.ts index 456b5b0a3a..3a37f33f47 100644 --- a/specification/enrich/stats/EnrichStatsResponse.ts +++ b/specification/enrich/stats/EnrichStatsResponse.ts @@ -21,9 +21,16 @@ import { ExecutingPolicy, CoordinatorStats, CacheStats } from './types' export class Response { body: { + /** + * Objects containing information about each coordinating ingest node for configured enrich processors. + */ coordinator_stats: CoordinatorStats[] + /** + * Objects containing information about each enrich policy that is currently executing. + */ executing_policies: ExecutingPolicy[] /** + * Objects containing information about the enrich cache stats on each ingest node. * @availability stack since=7.16.0 * @availability serverless */