Merge branch 'main' into cat-h-values-2

Author: kosabogi

Makefile

@@ -1,8 +1,7 @@
 SHELL := /bin/bash
 
-validate: ## Validate a given endpoint request or response
+validate: lint ## Validate a given endpoint request or response
 	@node compiler/run-validations.js --api $(api) --type $(type) --branch $(branch)
-	@npm run lint --prefix specification
 
 validate-no-cache: ## Validate a given endpoint request or response without local cache
 	@node compiler/run-validations.js --api $(api) --type $(type) --branch $(branch) --no-cache
@@ -86,6 +85,9 @@ generate-language-examples-with-java:
 	@node docs/examples/generate-language-examples.js java
 	@npm run format:fix-examples --prefix compiler
 
+lint:
+	@npm run lint --prefix specification
+
 lint-docs: ## Lint the OpenAPI documents after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
@@ -95,7 +97,7 @@ lint-docs-stateful: ## Lint only the elasticsearch-openapi-docs-final.json file
 lint-docs-serverless: ## Lint only the serverless OpenAPI document after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi-docs-final.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
-contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs ## Pre contribution target
+contrib: | lint generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs ## Pre contribution target
 
 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)

compiler/src/model/utils.ts

@@ -724,6 +724,11 @@ export function hoistRequestAnnotations (
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on request ${request.name.name}`)
     }
   })
+
+  if (endpoint.availability.stack?.visibility !== 'private') {
+    assert(jsDocs, tags.doc_id !== '' && tags.doc_id !== null && tags.doc_id !== undefined,
+      `Request ${request.name.name} needs a @doc_id annotation`)
+  }
 }
 
 /** Lifts jsDoc type annotations to fixed properties on Type */

compiler/test/body-codegen-name/specification/_global/index/request.ts

@@ -20,6 +20,7 @@
 /**
  * @rest_spec_name index
  * @availability stack since=0.0.0 stability=stable
+ * @doc_id docs-index
  */
 export interface Request {
   body: Foo

compiler/test/duplicate-body-codegen-name/specification/_global/index/request.ts

@@ -20,6 +20,7 @@
 /**
  * @rest_spec_name index
  * @availability stack since=0.0.0 stability=stable
+ * @doc_id docs-index
  */
 export interface Request {
   path_parts: {

compiler/test/no-body/specification/_global/info/request.ts

@@ -20,6 +20,7 @@
 /**
  * @rest_spec_name info
  * @availability stack since=0.0.0 stability=stable
+ * @doc_id api-root
  */
 export interface Request {
   body: {

compiler/test/no-doc-id/specification/_global/info/request.ts

@@ -0,0 +1,28 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * @rest_spec_name index
+ * @availability stack since=0.0.0 stability=stable
+ */
+export interface Request {
+  body: {
+    foo: string
+  }
+}

compiler/test/no-doc-id/specification/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../../specification/tsconfig.json",
+  "typeRoots": ["./**/*.ts"],
+  "include": ["./**/*.ts"]
+}

compiler/test/no-doc-id/test.ts

@@ -0,0 +1,32 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { join } from 'path'
+import test from 'ava'
+import Compiler from '../../src/compiler'
+import * as Model from '../../src/model/metamodel'
+
+const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
+
+test("Body cannot be defined if the API methods don't allow it", t => {
+  const compiler = new Compiler(specsFolder, outputFolder)
+  const error = t.throws(() => compiler.generateModel())
+  t.is(error?.message, "Request Request needs a @doc_id annotation")
+})

compiler/test/request-availability/specification/_global/index/request.ts

@@ -21,6 +21,7 @@
  * @rest_spec_name index
  * @availability serverless visibility=private stability=experimental
  * @availability stack stability=beta since=1.2.3 visibility=feature_flag feature_flag=abc
+ * @doc_id docs-index
  */
 export interface Request<TDocument> {
   path_parts: {

compiler/test/request-fields/specification/_global/index/request.ts

@@ -20,6 +20,7 @@
 /**
  * @rest_spec_name index
  * @availability stack stability=stable since=0.0.0
+ * @doc_id docs-index
  */
 export interface Request<TDocument> {
   path_parts: {