Enforce doc_id tag on public APIs

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

compiler/test/types/test.ts

@@ -92,7 +92,7 @@ test('type_alias', t => {
 test('request', t => {
   const definition = model.types.find(t => t.kind === 'request') as Model.Request
   t.assert(definition)
-  t.true(definition?.specLocation.endsWith('test/types/specification/_global/info/request.ts#L20-L24'))
+  t.true(definition?.specLocation.endsWith('test/types/specification/_global/info/request.ts#L20-L25'))
   t.deepEqual(definition?.name, {
     name: 'Request',
     namespace: '_global.info'

compiler/test/writes-to-output/specification/_global/index/request.ts

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

compiler/test/wrong-namespace/specification/_global/foobar/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 {}

specification/_doc_ids/table.csv

@@ -157,8 +157,10 @@ dangling-indices-list,https://www.elastic.co/docs/api/doc/elasticsearch/operatio
 data-processor,https://www.elastic.co/docs/reference/enrich-processor/date-processor,,
 data-stream-delete,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete-data-stream,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/indices-delete-data-stream.html,
 data-stream-delete-lifecycle,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete-data-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-streams-delete-lifecycle.html,
+data-stream-delete-options,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete-data-stream-options,
 data-stream-explain-lifecycle,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-explain-data-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-streams-explain-lifecycle.html,
 data-stream-get,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-stream,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/indices-get-data-stream.html,
+data-stream-get-options,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-stream-options,
 data-stream-get-lifecycle,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-streams-get-lifecycle.html,
 data-stream-lifecycle,https://www.elastic.co/docs/manage-data/lifecycle/data-stream,,
 data-stream-lifecycle-stats,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-lifecycle-stats,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-streams-get-lifecycle-stats.html,
@@ -167,6 +169,7 @@ data-stream-promote,https://www.elastic.co/docs/api/doc/elasticsearch/operation/
 data-stream-put-lifecycle,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-data-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-streams-put-lifecycle.html,
 data-stream-stats-api,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-data-streams-stats-1,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-stream-stats-api.html,
 data-stream-update,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-modify-data-stream,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/modify-data-streams-api.html,
+data-stream-update-options,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-data-stream-options,,
 data-streams,https://www.elastic.co/docs/manage-data/data-store/data-streams,,
 date-index-name-processor,https://www.elastic.co/docs/reference/enrich-processor/date-index-name-processor,,
 dcg,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/search-rank-eval#_discounted_cumulative_gain_dcg,,
@@ -221,6 +224,8 @@ esql-async-query-stop,https://www.elastic.co/docs/api/doc/elasticsearch/operatio
 esql-query,https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-rest,,
 esql-query-params,https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-rest#esql-rest-params,,
 esql-returning-localized-results,https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-rest#esql-locale-param,,
+esql-get-query,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-get-query,,
+esql-list-queries,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-list-queries,,
 evaluate-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-evaluate-data-frame,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/evaluate-dfanalytics.html,
 execute-enrich-policy-api,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-enrich-execute-policy,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/execute-enrich-policy-api.html,
 execute-watch,https://www.elastic.co/docs/explore-analyze/alerts-cases/watcher/execute-watch,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/watcher-api-execute-watch.html,

specification/esql/get_query/GetQueryRequest.ts

@@ -28,6 +28,7 @@ import { Id } from '@_types/common'
  * @cluster_privileges monitor_esql
  * @availability stack since=9.1.0 stability=experimental visibility=public
  * @availability serverless stability=experimental visibility=public
+ * @doc_id esql-get-query
  */
 export interface Request extends RequestBase {
   urls: [

specification/esql/list_queries/ListQueriesRequest.ts

@@ -27,6 +27,7 @@ import { RequestBase } from '@_types/Base'
  * @cluster_privileges monitor_esql
  * @availability stack since=9.1.0 stability=experimental visibility=public
  * @availability serverless stability=experimental visibility=public
+ * @doc_id esql-list-queries
  */
 export interface Request extends RequestBase {
   urls: [

specification/indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts

@@ -27,6 +27,8 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name indices.delete_data_stream_options
  * @availability stack since=8.19.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @doc_tag data stream
+ * @doc_id data-stream-delete-options
  */
 export interface Request extends RequestBase {
   urls: [

specification/indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts

@@ -29,6 +29,7 @@ import { Duration } from '@_types/Time'
  * @availability stack since=8.19.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_tag data stream
+ * @doc_id data-stream-get-options
  */
 export interface Request extends RequestBase {
   urls: [

specification/indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts

@@ -29,6 +29,7 @@ import { DataStreamFailureStore } from '@indices/_types/DataStreamFailureStore'
  * @availability stack since=8.19.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_tag data stream
+ * @doc_id data-stream-update-options
  */
 export interface Request extends RequestBase {
   urls: [