[ML] Extract apiDoc params from the schema definitions

x-pack/plugins/ml/package.json

@@ -0,0 +1,15 @@
+{
+  "author": "Elastic",
+  "name": "ml",
+  "version": "0.0.0",
+  "private": true,
+  "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  -i . -o ../routes_doc && apidoc-markdown --multi --createPath -p ../routes_doc -o ../routes_doc/md/"
+  },
+  "devDependencies": {
+    "apidoc": "^0.20.1",
+    "apidoc-markdown": "^5.0.0"
+  }
+}

x-pack/plugins/ml/server/routes/README.md

@@ -6,11 +6,14 @@ Each route handler requires [apiDoc](https://github.com/apidoc/apidoc) annotatio
 to generate documentation.
 The [apidoc-markdown](https://github.com/rigwild/apidoc-markdown) package is also required in order to generate the markdown.
 
-For now the process is pretty manual. You need to make sure the packages mentioned above are installed globally 
-to execute the following command from the directory in which this README file is located.
+There are custom parser and worker (`x-pack/plugins/ml/server/routes/apidoc_scripts`) to process api schemas for each documentation entry. It's written with typescript so make sure all the scripts in the folder are compiled before executing `apidoc` command.
+
+Make sure you have run `yarn kbn bootstrap` to get all requires dev dependencies. Then execute the following command from the ml plugin folder: 
 ```
-apidoc -i . -o ../routes_doc && apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.md 
+yarn run apiDocs
 ```
+It compiles all the required scripts and generates the documentation both in HTML and Markdown formats.
+
 
 It will create a new directory `routes_doc` (next to the `routes` folder) which contains the documentation in HTML format 
-as well as `ML_API.md` file.
+as well as markdown files under `/md` folder.

x-pack/plugins/ml/server/routes/annotations.ts

@@ -5,10 +5,8 @@
  */
 
 import Boom from 'boom';
-import _ from 'lodash';
 import { i18n } from '@kbn/i18n';
 
-import { schema } from '@kbn/config-schema';
 import { SecurityPluginSetup } from '../../../security/server';
 import { isAnnotationsFeatureAvailable } from '../lib/check_annotations';
 import { annotationServiceProvider } from '../models/annotation_service';
@@ -45,10 +43,7 @@ export function annotationRoutes(
    * @apiName GetAnnotations
    * @apiDescription Gets annotations.
    *
-   * @apiParam {String[]} jobIds List of job IDs
-   * @apiParam {String} earliestMs
-   * @apiParam {Number} latestMs
-   * @apiParam {Number} maxAnnotations Max limit of annotations returned
+   * @apiSchema (body) getAnnotationsSchema
    *
    * @apiSuccess {Boolean} success
    * @apiSuccess {Object} annotations
@@ -57,7 +52,7 @@ export function annotationRoutes(
     {
       path: '/api/ml/annotations',
       validate: {
-        body: schema.object(getAnnotationsSchema),
+        body: getAnnotationsSchema,
       },
     },
     mlLicense.fullLicenseAPIGuard(async (context, request, response) => {
@@ -83,14 +78,13 @@ export function annotationRoutes(
    * @apiName IndexAnnotations
    * @apiDescription Index the annotation.
    *
-   * @apiParam {Object} annotation
-   * @apiParam {String} username
+   * @apiSchema (body) indexAnnotationSchema
    */
   router.put(
     {
       path: '/api/ml/annotations/index',
       validate: {
-        body: schema.object(indexAnnotationSchema),
+        body: indexAnnotationSchema,
       },
     },
     mlLicense.fullLicenseAPIGuard(async (context, request, response) => {
@@ -124,17 +118,17 @@ export function annotationRoutes(
   /**
    * @apiGroup Annotations
    *
-   * @api {delete} /api/ml/annotations/index Deletes annotation
+   * @api {delete} /api/ml/annotations/delete/:annotationId Deletes annotation
    * @apiName DeleteAnnotation
    * @apiDescription Deletes specified annotation
    *
-   * @apiParam {String} annotationId
+   * @apiSchema (params) deleteAnnotationSchema
    */
   router.delete(
     {
       path: '/api/ml/annotations/delete/{annotationId}',
       validate: {
-        params: schema.object(deleteAnnotationSchema),
+        params: deleteAnnotationSchema,
       },
     },
     mlLicense.fullLicenseAPIGuard(async (context, request, response) => {