diff --git a/compiler/src/model/utils.ts b/compiler/src/model/utils.ts index ccc0647bc4..3822274220 100644 --- a/compiler/src/model/utils.ts +++ b/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 */ diff --git a/compiler/test/body-codegen-name/specification/_global/index/request.ts b/compiler/test/body-codegen-name/specification/_global/index/request.ts index e2336b40d5..b18e03f3b7 100644 --- a/compiler/test/body-codegen-name/specification/_global/index/request.ts +++ b/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 diff --git a/compiler/test/duplicate-body-codegen-name/specification/_global/index/request.ts b/compiler/test/duplicate-body-codegen-name/specification/_global/index/request.ts index 2b86f0b488..7b3193bc6a 100644 --- a/compiler/test/duplicate-body-codegen-name/specification/_global/index/request.ts +++ b/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: { diff --git a/compiler/test/no-body/specification/_global/info/request.ts b/compiler/test/no-body/specification/_global/info/request.ts index 4211111f7d..ddf89ba1cf 100644 --- a/compiler/test/no-body/specification/_global/info/request.ts +++ b/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: { diff --git a/compiler/test/no-doc-id/specification/_global/info/request.ts b/compiler/test/no-doc-id/specification/_global/info/request.ts new file mode 100644 index 0000000000..3d33c90fdd --- /dev/null +++ b/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 + } +} diff --git a/compiler/test/no-doc-id/specification/tsconfig.json b/compiler/test/no-doc-id/specification/tsconfig.json new file mode 100644 index 0000000000..a983782068 --- /dev/null +++ b/compiler/test/no-doc-id/specification/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "../../../../specification/tsconfig.json", + "typeRoots": ["./**/*.ts"], + "include": ["./**/*.ts"] +} diff --git a/compiler/test/no-doc-id/test.ts b/compiler/test/no-doc-id/test.ts new file mode 100644 index 0000000000..e88625f9c7 --- /dev/null +++ b/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") +}) diff --git a/compiler/test/request-availability/specification/_global/index/request.ts b/compiler/test/request-availability/specification/_global/index/request.ts index fc01b2ce91..b69746c3e3 100644 --- a/compiler/test/request-availability/specification/_global/index/request.ts +++ b/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 { path_parts: { diff --git a/compiler/test/request-fields/specification/_global/index/request.ts b/compiler/test/request-fields/specification/_global/index/request.ts index 62f4132f05..3a766fbabf 100644 --- a/compiler/test/request-fields/specification/_global/index/request.ts +++ b/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 { path_parts: { diff --git a/compiler/test/types/specification/_global/info/request.ts b/compiler/test/types/specification/_global/info/request.ts index baa16a9e5d..7813b1aba3 100644 --- a/compiler/test/types/specification/_global/info/request.ts +++ b/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 {} diff --git a/compiler/test/types/test.ts b/compiler/test/types/test.ts index 2761108f21..787eabeb78 100644 --- a/compiler/test/types/test.ts +++ b/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' diff --git a/compiler/test/writes-to-output/specification/_global/index/request.ts b/compiler/test/writes-to-output/specification/_global/index/request.ts index 30c5436179..622a012cfd 100644 --- a/compiler/test/writes-to-output/specification/_global/index/request.ts +++ b/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 {} \ No newline at end of file diff --git a/compiler/test/wrong-namespace/specification/_global/foobar/request.ts b/compiler/test/wrong-namespace/specification/_global/foobar/request.ts index baa16a9e5d..7813b1aba3 100644 --- a/compiler/test/wrong-namespace/specification/_global/foobar/request.ts +++ b/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 {} diff --git a/output/schema/schema.json b/output/schema/schema.json index 9d06cc06ee..f1c7ec17e5 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -5203,7 +5203,8 @@ } }, "description": "Get a specific running ES|QL query information.\nReturns an object extended information about a running ES|QL query.", - "docUrl": null, + "docId": "esql-get-query", + "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-get-query", "name": "esql.get_query", "privileges": { "cluster": [ @@ -5247,7 +5248,8 @@ } }, "description": "Get running ES|QL queries information.\nReturns an object containing IDs and other information about the running ES|QL queries.", - "docUrl": null, + "docId": "esql-list-queries", + "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-list-queries", "name": "esql.list_queries", "privileges": { "cluster": [ @@ -7184,7 +7186,9 @@ } }, "description": "Delete data stream options.\nRemoves the data stream options from a data stream.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html", + "docId": "data-stream-delete-options", + "docTag": "data stream", + "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-delete-data-stream-options", "name": "indices.delete_data_stream_options", "request": { "name": "Request", @@ -7992,8 +7996,9 @@ } }, "description": "Get data stream options.\n\nGet the data stream options configuration of one or more data streams.", + "docId": "data-stream-get-options", "docTag": "data stream", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html", + "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-stream-options", "name": "indices.get_data_stream_options", "request": { "name": "Request", @@ -8686,8 +8691,9 @@ } }, "description": "Update data stream options.\nUpdate the data stream options of the specified data streams.", + "docId": "data-stream-update-options", "docTag": "data stream", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html", + "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-data-stream-options", "name": "indices.put_data_stream_options", "request": { "name": "Request", @@ -139537,7 +139543,7 @@ } ], "query": [], - "specLocation": "esql/get_query/GetQueryRequest.ts#L23-L42" + "specLocation": "esql/get_query/GetQueryRequest.ts#L23-L43" }, { "kind": "response", @@ -139718,7 +139724,7 @@ }, "path": [], "query": [], - "specLocation": "esql/list_queries/ListQueriesRequest.ts#L22-L38" + "specLocation": "esql/list_queries/ListQueriesRequest.ts#L22-L39" }, { "kind": "response", @@ -153516,7 +153522,7 @@ } } ], - "specLocation": "indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts#L24-L46" + "specLocation": "indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts#L24-L48" }, { "kind": "response", @@ -156974,7 +156980,7 @@ } } ], - "specLocation": "indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts#L24-L61" + "specLocation": "indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts#L24-L62" }, { "kind": "response", @@ -159801,7 +159807,7 @@ } } ], - "specLocation": "indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts#L25-L79" + "specLocation": "indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts#L25-L80" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 9286ae6d95..a7ab2c8eea 100644 --- a/specification/_doc_ids/table.csv +++ b/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, diff --git a/specification/esql/get_query/GetQueryRequest.ts b/specification/esql/get_query/GetQueryRequest.ts index f7836755d6..6242553a88 100644 --- a/specification/esql/get_query/GetQueryRequest.ts +++ b/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: [ diff --git a/specification/esql/list_queries/ListQueriesRequest.ts b/specification/esql/list_queries/ListQueriesRequest.ts index e52f1bf880..06c353f4dd 100644 --- a/specification/esql/list_queries/ListQueriesRequest.ts +++ b/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: [ diff --git a/specification/indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts b/specification/indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts index 27e860f0a7..e58b4ca6a9 100644 --- a/specification/indices/delete_data_stream_options/IndicesDeleteDataStreamOptionsRequest.ts +++ b/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: [ diff --git a/specification/indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts b/specification/indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts index 9c73736c7f..0595dbe958 100644 --- a/specification/indices/get_data_stream_options/IndicesGetDataStreamOptionsRequest.ts +++ b/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: [ diff --git a/specification/indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts b/specification/indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts index 0b0cc4e290..9bfd90f1e5 100644 --- a/specification/indices/put_data_stream_options/IndicesPutDataStreamOptionsRequest.ts +++ b/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: [