From afc65b5008a743d7218797701eee303b998f89a2 Mon Sep 17 00:00:00 2001
From: delvedor <tommydelved@gmail.com>
Date: Tue, 14 Sep 2021 09:04:23 +0200
Subject: [PATCH] Add support for doc_id

---
 compiler/model/metamodel.ts |  1 +
 compiler/model/utils.ts     |  5 ++++-
 docs/modeling-guide.md      | 15 +++++++++++++++
 3 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/compiler/model/metamodel.ts b/compiler/model/metamodel.ts
index 9651c330a2..13c325aa70 100644
--- a/compiler/model/metamodel.ts
+++ b/compiler/model/metamodel.ts
@@ -339,6 +339,7 @@ export class Endpoint {
   name: string
   description: string
   docUrl: string
+  docId?: string
   deprecation?: Deprecation
 
   /**
diff --git a/compiler/model/utils.ts b/compiler/model/utils.ts
index 9e75ccec32..49d20650b5 100644
--- a/compiler/model/utils.ts
+++ b/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}`)
     }
diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md
index 33dc47e645..e8d3aed172 100644
--- a/docs/modeling-guide.md
+++ b/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