From f7a89601c79ba4320f71857ea92859b2b726c058 Mon Sep 17 00:00:00 2001
From: Dima Arnautov <dmitrii.arnautov@elastic.co>
Date: Fri, 15 May 2020 11:41:29 +0200
Subject: [PATCH] [ML] Custom template for apiDoc markdown (#66567)

* [ML] custom template for apiDoc markdown

* [ML] update apiDoc description
---
 x-pack/plugins/ml/package.json                |   2 +-
 x-pack/plugins/ml/server/routes/apidoc.json   |   2 +-
 .../server/routes/apidoc_scripts/template.md  | 143 ++++++++++++++++++
 3 files changed, 145 insertions(+), 2 deletions(-)
 create mode 100644 x-pack/plugins/ml/server/routes/apidoc_scripts/template.md

diff --git a/x-pack/plugins/ml/package.json b/x-pack/plugins/ml/package.json
index 739dd806fcbb9..d69d6657fe68c 100644
--- a/x-pack/plugins/ml/package.json
+++ b/x-pack/plugins/ml/package.json
@@ -6,7 +6,7 @@
   "license": "Elastic-License",
   "scripts": {
     "build:apiDocScripts": "cd server/routes/apidoc_scripts && tsc",
-    "apiDocs": "yarn build:apiDocScripts && cd ./server/routes/ && apidoc --parse-workers apischema=./apidoc_scripts/target/schema_worker.js --parse-parsers apischema=./apidoc_scripts/target/schema_parser.js --parse-filters apiversion=./apidoc_scripts/target/version_filter.js  -i . -o ../routes_doc && apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.md"
+    "apiDocs": "yarn build:apiDocScripts && cd ./server/routes/ && apidoc --parse-workers apischema=./apidoc_scripts/target/schema_worker.js --parse-parsers apischema=./apidoc_scripts/target/schema_parser.js --parse-filters apiversion=./apidoc_scripts/target/version_filter.js  -i . -o ../routes_doc && apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.md -t ./apidoc_scripts/template.md"
   },
   "devDependencies": {
     "apidoc": "^0.20.1",
diff --git a/x-pack/plugins/ml/server/routes/apidoc.json b/x-pack/plugins/ml/server/routes/apidoc.json
index cd311c285d0df..c2cb1ad9f0a57 100644
--- a/x-pack/plugins/ml/server/routes/apidoc.json
+++ b/x-pack/plugins/ml/server/routes/apidoc.json
@@ -1,7 +1,7 @@
 {
   "name": "ml_kibana_api",
   "version": "7.8.0",
-  "description": "ML Kibana API",
+  "description": "This is the documentation of the REST API provided by the Machine Learning Kibana plugin. Each API is experimental and can include breaking changes in any version.",
   "title": "ML Kibana API",
   "order": [
     "DataFrameAnalytics",
diff --git a/x-pack/plugins/ml/server/routes/apidoc_scripts/template.md b/x-pack/plugins/ml/server/routes/apidoc_scripts/template.md
new file mode 100644
index 0000000000000..70de461da18d8
--- /dev/null
+++ b/x-pack/plugins/ml/server/routes/apidoc_scripts/template.md
@@ -0,0 +1,143 @@
+<a name="top"></a>
+# <%= project.name %> v<%= project.version %>
+
+<%= project.description %>
+
+<% if (prepend) { -%>
+<%- prepend %>
+<% } -%>
+<% data.forEach(group => { -%>
+
+## <a name='<%= toLink(group.name) %>'></a> <%= group.name %>
+<% group.subs.forEach(sub => { -%>
+
+### <a name='<%= toLink(sub.title) %>'></a> <%= sub.title %>
+[Back to top](#top)
+
+<%- sub.description ? `${sub.description}\n\n` : '' -%>
+```
+<%- sub.type.toUpperCase() %> <%= sub.url %>
+```
+<% if (sub.header && sub.header.fields && sub.header.fields.Header.length) { -%>
+
+#### Headers
+| Name    | Type      | Description                          |
+|---------|-----------|--------------------------------------|
+<% sub.header.fields.Header.forEach(header => { -%>
+| <%- header.field %> | <%- header.type ? `\`${header.type}\`` : '' %> | <%- header.optional ? '**optional**' : '' %><%- header.description %> |
+<% }) // foreach parameter -%>
+<% } // if parameters -%>
+<% if (sub.header && sub.header.examples && sub.header.examples.length) { -%>
+
+#### Header examples
+<% sub.header.examples.forEach(example => { -%>
+<%= example.title %>
+
+```
+<%- example.content %>
+```
+<% }) // foreach example -%>
+<% } // if example -%>
+<% if (sub.parameter && sub.parameter.fields) { -%>
+<% Object.keys(sub.parameter.fields).forEach(g => { -%>
+
+#### Parameters - `<%= g -%>`
+| Name     | Type       | Description                           |
+|:---------|:-----------|:--------------------------------------|
+<% sub.parameter.fields[g].forEach(param => { -%>
+| <%- param.field -%> | <%- param.type ? `\`${param.type}\`` : '' %> | <%- param.optional ? '**optional** ' : '' -%><%- param.description -%>
+<% if (param.defaultValue) { -%>
+_Default value: <%= param.defaultValue %>_<br><% } -%>
+<% if (param.size) { -%>
+_Size range: <%- param.size %>_<br><% } -%>
+<% if (param.allowedValues) { -%>
+_Allowed values: <%- param.allowedValues %>_<% } -%> |
+<% }) // foreach (group) parameter -%>
+<% }) // foreach param parameter -%>
+<% } // if parameters -%>
+<% if (sub.examples && sub.examples.length) { -%>
+
+#### Examples
+<% sub.examples.forEach(example => { -%>
+<%= example.title %>
+
+```
+<%- example.content %>
+```
+<% }) // foreach example -%>
+<% } // if example -%>
+<% if (sub.parameter && sub.parameter.examples && sub.parameter.examples.length) { -%>
+
+#### Parameters examples
+<% sub.parameter.examples.forEach(exampleParam => { -%>
+`<%= exampleParam.type %>` - <%= exampleParam.title %>
+
+```<%= exampleParam.type %>
+<%- exampleParam.content %>
+```
+<% }) // foreach exampleParam -%>
+<% } // if exampleParam -%>
+<% if (sub.success && sub.success.fields) { -%>
+
+#### Success response
+<% Object.keys(sub.success.fields).forEach(g => { -%>
+
+##### Success response - `<%= g %>`
+| Name     | Type       | Description                           |
+|:---------|:-----------|:--------------------------------------|
+<% sub.success.fields[g].forEach(param => { -%>
+| <%- param.field %> | <%- param.type ? `\`${param.type}\`` : '' %> | <%- param.optional ? '**optional**' : '' %><%- param.description -%>
+<% if (param.defaultValue) { -%>
+_Default value: <%- param.defaultValue %>_<br><% } -%>
+<% if (param.size) { -%>
+_Size range: <%- param.size -%>_<br><% } -%>
+<% if (param.allowedValues) { -%>
+_Allowed values: <%- param.allowedValues %>_<% } -%> |
+<% }) // foreach (group) parameter -%>
+<% }) // foreach field -%>
+<% } // if success.fields -%>
+<% if (sub.success && sub.success.examples && sub.success.examples.length) { -%>
+
+#### Success response example
+<% sub.success.examples.forEach(example => { -%>
+
+##### Success response example - `<%= example.title %>`
+
+```
+<%- example.content %>
+```
+<% }) // foreach success example -%>
+<% } // if success.examples -%>
+<% if (sub.error && sub.error.fields) { -%>
+
+#### Error response
+<% Object.keys(sub.error.fields).forEach(g => { -%>
+
+##### Error response - `<%= g %>`
+| Name     | Type       | Description                           |
+|:---------|:-----------|:--------------------------------------|
+<% sub.error.fields[g].forEach(param => { -%>
+| <%- param.field %> | <%- param.type ? `\`${param.type}\`` : '' %> | <%- param.optional ? '**optional**' : '' %><%- param.description -%>
+<% if (param.defaultValue) { -%>
+_Default value: <%- param.defaultValue %>_<br><% } -%>
+<% if (param.size) { -%>
+_Size range: <%- param.size -%>_<br><% } -%>
+<% if (param.allowedValues) { -%>
+_Allowed values: <%- param.allowedValues %>_<% } -%> |
+<% }) // foreach (group) parameter -%>
+<% }) // foreach field -%>
+<% } // if error.fields -%>
+<% if (sub.error && sub.error.examples && sub.error.examples.length) { -%>
+
+#### Error response example
+<% sub.error.examples.forEach(example => { -%>
+
+##### Error response example - `<%= example.title %>`
+
+```
+<%- example.content %>
+```
+<% }) // foreach error example -%>
+<% } // if error.examples -%>
+<% }) // foreach sub -%>
+<% }) // foreach group -%>