[OpenAPI] Add list of tags in overlay (#2905)

Author: lcawl

.spectral.yaml

@@ -17,7 +17,7 @@ rules:
   operation-operationId: warn
   operation-operationId-unique: warn
   operation-operationId-valid-in-url: warn
-  operation-tag-defined: warn
+  operation-tag-defined: error
   operation-tags: warn
   # Parameters
   path-params: warn

Makefile

@@ -69,14 +69,14 @@ overlay-docs: ## Apply overlays to OpenAPI documents
 	rm output/openapi/elasticsearch-serverless-openapi.tmp*.json
 	rm output/openapi/elasticsearch-openapi.tmp*.json
 
-lint-docs: ## Lint the OpenAPI documents
-	@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml
+lint-docs: ## Lint the OpenAPI documents after overlays
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-*.examples.json --ruleset .spectral.yaml
 
-lint-docs-errs: ## Lint the OpenAPI documents and return only errors
-	@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml -D
+lint-docs-errs: ## Lint the OpenAPI documents after overlays and return only errors
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-*.examples.json --ruleset .spectral.yaml -D
 
-lint-docs-serverless: ## Lint only the serverless OpenAPI document
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json --ruleset .spectral.yaml
+lint-docs-serverless: ## Lint only the serverless OpenAPI document after overlays
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.examples.json --ruleset .spectral.yaml
 
 help:  ## Display help
 	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

docs/overlays/elasticsearch-serverless-openapi-overlays.yaml

@@ -4,6 +4,227 @@ info:
   title: Overlays for changes that apply to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
   version: 0.0.1
 actions:
+# Add x-model to hide children of schema objects that are defined elsewhere
+  - target: "$.components['schemas']['_types.query_dsl:QueryContainer']"
+    description: Add x-model and updated externalDocs for the QueryContainer object
+    update:
+      x-model: true
+      externalDocs:
+        url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+        description: Query domain specific language (DSL) reference
+# Add an alphabetically sorted list of tags
+  - target: '$'
+    description: Add document-level tags sorted by display name
+    update:
+      tags:
+      # A
+        - name: autoscaling
+          x-displayName: Autoscaling
+      # B
+        - name: analytics
+          x-displayName: Behavioral analytics
+      # C 
+        - name: cat
+          x-displayName: Compact and aligned text (CAT)
+          description: >
+            The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line.
+            They are not intended for use by applications.
+            For application consumption, it's recommend to use a corresponding JSON API.
+            
+            All the cat commands accept a query string parameter `help` to see all the headers and info they provide, and the `/_cat` command alone lists all the available commands.
+        - name: cluster
+          x-displayName: Cluster
+        - name: health_report
+          x-displayName: Cluster - Health
+        - name: connector
+          x-displayName: Connector
+          description: >
+            The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index.
+            
+            Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure:
+            
+            * Native connectors are a managed service on Elastic Cloud
+            * Connector clients are self-managed on your infrastructure
+            
+            This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/enterprise-search/current/connectors-tutorial-api.html
+            description: To get started with Connector APIs, check out the tutorial.
+        - name: ccr
+          x-displayName: Cross-cluster replication
+      # D
+        - name: data stream
+          x-displayName: Data stream
+          externalDocs:
+            description: Data stream overview 
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html
+        - name: document
+          x-displayName: Document
+          externalDocs:
+            description: Reading and writing documents
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-replication.html
+        - name: mget
+          x-displayName: Document - Multi get
+        - name: mtermvectors
+          x-displayName: Document - Multi term vectors
+        - name: delete_by_query_rethrottle
+          x-displayName: Document - Rethrottle delete by query
+        - name: update_by_query_rethrottle
+          x-displayName: Document - Rethrottle update by query
+      # E  
+        - name: enrich
+          x-displayName: Enrich
+        - name: eql
+          x-displayName: EQL
+          description: >
+            Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html
+            description: EQL search
+        - name: esql
+          x-displayName: ES|QL
+          description: >
+            The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html
+            description: ES|QL overview and tutorials
+      # F
+        - name: features
+          description: The feature APIs enable you to introspect and manage features provided by Elasticsearch and Elasticsearch plugins.
+          x-displayName: Features
+        - name: fleet
+          x-displayName: Fleet
+      # G
+        - name: graph
+          x-displayName: Graph explore
+          description: >
+            The graph explore API enables you to extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/kibana/current/xpack-graph.html
+            description: Getting started with Graph
+      # I
+        - name: indices
+          x-displayName: Index
+          description: >
+            Index APIs enable you to manage individual indices, index settings, aliases, mappings, and index templates.
+        - name: dangling_indices
+          x-displayName: Index - Import dangling index
+        - name: ilm
+          x-displayName: Index lifecycle management
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html
+            description: Manage the index lifecycle
+        - name: inference
+          x-displayName: Inference
+          description: >
+            Inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio or Hugging Face.
+            For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models.
+            However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
+        - name: info
+          x-displayName: Info
+        - name: ingest
+          x-displayName: Ingest
+          description: Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.
+      # L  
+        - name: license
+          x-displayName: Licensing
+          description: Licensing APIs enable you to manage your licenses.
+        - name: logstash
+          x-displayName: Logstash
+          description: >
+            Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html
+            description: Centralized pipeline management
+      # M
+        - name: ml
+          x-displayName: Machine learning
+        - name: migration
+          x-displayName: Migration
+        - name: monitoring
+          x-displayName: Monitoring
+      # N
+        - name: shutdown
+          x-displayName: Node lifecycle
+      # Q
+        - name: query_rules
+          x-displayName: Query rules
+          description: >
+            Query rules enable you to configure per-query rules that are applied at query time to queries that match the specific rule.
+            Query rules are organized into rulesets, collections of query rules that are matched against incoming queries.
+            Query rules are applied using the rule query.
+            
+            If a query matches one or more rules in the ruleset, the query is re-written to apply the rules before searching.
+            This allows pinning documents for only queries that match a specific term.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rule-query.html
+            description: Rule query
+      # R
+        - name: rollup
+          x-displayName: Rollup
+      # S
+        - name: script
+          x-displayName: Script
+        - name: get_script_context
+          x-displayName: Script - Get contexts
+        - name: get_script_languages
+          x-displayName: Script - Get languages
+        - name: search
+          x-displayName: Search
+        - name: msearch
+          x-displayName: Search - Multi search
+        - name: scroll
+          x-displayName: Search - Scroll
+        - name: terms_enum
+          x-displayName: Search - Terms enum
+        - name: search_application
+          x-displayName: Search application
+        - name: searchable_snapshots
+          x-displayName: Searchable snapshots
+        - name: security
+          x-displayName: Security
+        - name: ssl
+          x-displayName: Security - SSL
+        - name: snapshot
+          x-displayName: Snapshot and restore
+          description: >
+            Snapshot and restore APIs enable you to set up snapshot repositories, manage snapshot backups, and restore snapshots to a running cluster.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html
+            description: Snapshot and restore
+        - name: slm
+          x-displayName: Snapshot lifecycle management
+          description: >
+            Snapshot lifecycle management (SLM) APIs enable you to set up policies to automatically take snapshots and control how long they are retained.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html
+            description: Create a snapshot
+        - name: sql
+          x-displayName: SQL
+          description: >
+            Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-sql.html
+            description: An overview and tutorials for the Elasticsearch SQL features
+        - name: synonyms
+          x-displayName: Synonyms
+          description: >
+            The synonyms management API provides a convenient way to define and manage synonyms in an internal system index.
+            Related synonyms can be grouped in a "synonyms set".
+            Create as many synonym sets as you need.
+      # T  
+        - name: tasks
+          x-displayName: Task management
+        - name: text_structure
+          x-displayName: Text structure
+        - name: transform
+          x-displayName: Transform
+      # U
+        - name: xpack
+          x-displayName: Usage
+      # W
+        - name: watcher
+          x-displayName: Watcher
 # Abbreviate and annotate items that are not shown in Bump.sh due to depth limits
   - target: "$.components['schemas']['ml._types:Datafeed'].properties.query"
     description: Remove query object from anomaly detection datafeed