Add operation summaries for index template APIs (#2634)

Author: lcawl

Makefile

@@ -60,7 +60,10 @@ dump-routes: ## Create a new schema with all generics expanded
 contrib: | generate license-check spec-format-fix transform-to-openapi ## Pre contribution target
 
 lint-docs: ## Lint the OpenAPI documents
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json
+	@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml
+
+lint-docs-serverless: ## Lint only the serverless OpenAPI document
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.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)

README.md

@@ -69,7 +69,13 @@ Usage:
   spec-dangling-types  Generate the dangling types rreport
   setup            Install dependencies for contrib target
   clean-dep        Clean npm dependencies
+  transform-expand-generics  Create a new schema with all generics expanded
+  transform-to-openapi  Generate the OpenAPI definition from the compiled schema
+  filter-for-serverless  Generate the serverless version from the compiled schema
+  dump-routes      Create a new schema with all generics expanded
   contrib          Pre contribution target
+  lint-docs        Lint the OpenAPI documents
+  lint-docs-serverless  Lint only the serverless OpenAPI document
   help             Display help
 ```
 

docs/doc-comments-guide.md

@@ -4,12 +4,19 @@ A specification is not only about formalizing data structures, it's also about e
 
 Documentation of the TypeScript specification is made using [JSDoc](https://jsdoc.app/) comments, i.e. multiline comments starting with `/**` above a type or field declaration.
 
+The first phrase is used as the mandatory operation summary in the OpenAPI document.
+Refer to [API documentation guidelines](https://docs.elastic.dev/content-architecture/oas#summaries).
+
+NOTE: You must add a period or `\n` at the end of the phrase for it to parse correctly.
+The period will be properly omitted from the output OpenAPI document.
+
 Additional lines start with a `*` followed by a space. Long lines are allowed but it's better if text is formatted to a maximum of 120 characters per line.
 
 ## Example
 
 ```ts
 /**
+ * Get ranking evaluation.
  * Enables you to evaluate the quality of ranked search results over a set of typical search queries.
  * @rest_spec_name rank_eval
  * @availability stack since=6.2.0 stability=stable

output/openapi/elasticsearch-openapi.json

@@ -11783,7 +11783,8 @@
         "tags": [
           "indices.get_index_template"
         ],
-        "summary": "Returns information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Returns information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template.html"
         },
@@ -11815,7 +11816,7 @@
         "tags": [
           "indices.put_index_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-put-template.html"
@@ -11848,7 +11849,7 @@
         "tags": [
           "indices.put_index_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-put-template.html"
@@ -11881,8 +11882,8 @@
         "tags": [
           "indices.delete_index_template"
         ],
-        "summary": "The provided <index-template> may contain multiple template names separated by a comma",
-        "description": "If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.",
+        "summary": "Delete an index template",
+        "description": "The provided <index-template> may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-delete-template.html"
         },
@@ -11980,7 +11981,8 @@
         "tags": [
           "indices.get_template"
         ],
-        "summary": "Retrieves information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Retrieves information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template-v1.html"
         },
@@ -12009,7 +12011,7 @@
         "tags": [
           "indices.put_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates-v1.html"
@@ -12045,7 +12047,7 @@
         "tags": [
           "indices.put_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates-v1.html"
@@ -12136,7 +12138,8 @@
         "tags": [
           "indices.exists_template"
         ],
-        "summary": "Returns information about whether a particular index template exists",
+        "summary": "Check existence of index templates",
+        "description": "Returns information about whether a particular index template exists.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-template-exists-v1.html"
         },
@@ -12975,7 +12978,8 @@
         "tags": [
           "indices.get_index_template"
         ],
-        "summary": "Returns information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Returns information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template.html"
         },
@@ -13426,7 +13430,8 @@
         "tags": [
           "indices.get_template"
         ],
-        "summary": "Retrieves information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Retrieves information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template-v1.html"
         },
@@ -14355,6 +14360,8 @@
         "tags": [
           "indices.simulate_index_template"
         ],
+        "summary": "Simulate an index",
+        "description": "Returns the index configuration that would be applied to the specified index from an existing index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-index.html"
         },
@@ -14425,7 +14432,8 @@
         "tags": [
           "indices.simulate_template"
         ],
-        "summary": "Returns the index configuration that would be applied by a particular index template",
+        "summary": "Simulate an index template",
+        "description": "Returns the index configuration that would be applied by a particular index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-template.html"
         },
@@ -14456,7 +14464,8 @@
         "tags": [
           "indices.simulate_template"
         ],
-        "summary": "Returns the index configuration that would be applied by a particular index template",
+        "summary": "Simulate an index template",
+        "description": "Returns the index configuration that would be applied by a particular index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-template.html"
         },