[OpenAPI] Add more x-model and @ext_doc_id values (#3048)

(cherry picked from commit dad2aa1)

Author: lcawl

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -9,10 +9,14 @@ actions:
     update:
       title: Elasticsearch API
       description: >
+        Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.
+        
         ## Documentation source and versions
         
         This documentation is derived from the `8.x` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
         It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
+
+        This documentation contains work-in-progress information for future Elastic Stack releases.
       x-doc-license:
         name: Attribution-NonCommercial-NoDerivatives 4.0 International
         url: 'https://creativecommons.org/licenses/by-nc-nd/4.0/'

docs/overlays/elasticsearch-shared-overlays.yaml

@@ -353,6 +353,17 @@ actions:
         externalDocs:
           url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
           description: Query DSL
+  - target: "$.components['schemas']['_global.search._types:FieldCollapse']"
+    description: Add x-model and externalDocs
+    update:
+      x-model: true
+      externalDocs:
+        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/collapse-search-results.html
+  - target: "$.components['schemas']['_global.msearch:MultisearchBody'].properties"
+    description: Add x-model
+    update:
+      aggregations:
+        x-model: true
 # Examples
   - target: "$.components['requestBodies']['async_search.submit']"
     description: "Add example for asynch search submit request"

output/openapi/elasticsearch-openapi.json

@@ -80,6 +80,7 @@ cluster,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster
 common-options,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/common-options.html
 community-id-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/community-id-processor.html
 connector-sync-job-cancel,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cancel-connector-sync-job-api.html
+collapse-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/collapse-search-results.html
 connector-sync-job-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-connector-sync-job-api.html
 connector-sync-job-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-connector-sync-job-api.html
 connector-sync-job-post,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-connector-sync-job-api.html

output/openapi/elasticsearch-serverless-openapi.json

@@ -68,7 +68,10 @@ export class MultisearchHeader {
 
 // We should keep this in sync with the normal search request body.
 export class MultisearchBody {
-  /** @aliases aggs */ // ES uses "aggregations" in serialization
+  /**
+   * @aliases aggs
+   * @ext_doc_id search-aggregations
+   */ // ES uses "aggregations" in serialization
   aggregations?: Dictionary<string, AggregationContainer>
   collapse?: FieldCollapse
   /**

output/schema/schema.json

@@ -21,6 +21,9 @@ import { Field } from '@_types/common'
 import { integer } from '@_types/Numeric'
 import { InnerHits } from './hits'
 
+/**
+ * @ext_doc_id collapse-search-results
+ */
 export class FieldCollapse {
   /**
    * The field to collapse the result set on