Enforce doc_id tag on public APIs (#5198) (#5228)

* Enforce doc_id tag on public APIs

* Fix tests

* Add doc_id test

(cherry picked from commit 01182b0)

# Conflicts:
#	output/schema/schema.json
#	specification/_doc_ids/table.csv
#	specification/esql/get_query/GetQueryRequest.ts
#	specification/esql/list_queries/ListQueriesRequest.ts
#	specification/indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts
#	specification/indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts
#	specification/indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts

Author: pquentin

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: {

compiler/test/types/specification/_global/info/request.ts

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