Add support for doc_id

compiler/model/metamodel.ts

@@ -339,6 +339,7 @@ export class Endpoint {
   name: string
   description: string
   docUrl: string
+  docId?: string
   deprecation?: Deprecation
 
   /**

compiler/model/utils.ts

@@ -516,7 +516,7 @@ export function hoistRequestAnnotations (
   request: model.Request, jsDocs: JSDoc[], mappings: Record<string, model.Endpoint>, response: model.TypeName | null
 ): void {
   const knownRequestAnnotations = [
-    'since', 'rest_spec_name', 'stability', 'visibility', 'behavior', 'class_serializer'
+    'since', 'rest_spec_name', 'stability', 'visibility', 'behavior', 'class_serializer', 'doc_id'
   ]
   // in most of the cases the jsDocs comes in a single block,
   // but it can happen that the user defines multiple single line jsDoc.
@@ -556,6 +556,9 @@ export function hoistRequestAnnotations (
     } else if (tag === 'since') {
       assert(jsDocs, semver.valid(value), `Request ${request.name.name}'s @since is not valid semver: ${value}`)
       endpoint.since = value
+    } else if (tag === 'doc_id') {
+      assert(jsDocs, value.trim() !== '', `Request ${request.name.name}'s @doc_id is cannot be empty`)
+      endpoint.docId = value
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on request ${request.name.name}`)
     }

docs/modeling-guide.md

@@ -433,6 +433,21 @@ class Foo {
 }
 ```
 
+#### `@doc_id`
+
+The documentation id that can be used for generating the doc url.
+See [#714](https://github.com/elastic/elasticsearch-specification/issues/714) for context.
+
+```ts
+/**
+ * @rest_spec_name api
+ * @doc_id foobar
+ */
+class Request {
+  ...
+}
+```
+
 #### `@identifier`
 
 A custom name that can be used to display the property. Useful in Enums an