Skip to content

Commit 8600a98

Browse files
darnautovelasticmachine
darnautov
and
elasticmachine
committed
[ML] Extract apiDoc params from the schema definitions (#62933)
* [ML] WIP apiDoc schema extractor * [ML] extract actual type * [ML] refactor schema definitions * [ML] Update README.md * [ML] extract nested * [ML] call job validation endpoint with complete payload * [ML] escape special chars and fix line breaks * [ML] clean up extractDocEntries * [ML] serializeWithType * [ML] add missing annotations * [ML] fix parent schema assigment * [ML] support object composition * [ML] support multiple schemas per block * [ML] fix for collections * [ML] fix calendarIdsSchema * [ML] add ml package.json with apidoc commands * [ML] use the single output markdown file * [ML] fix typo * [ML] change the Calendars order * [ML] adjust the order in adidoc.json * [ML] update api version * [ML] update tsconfig.json include * [ML] update packages/kbn-pm/dist/index.js * [ML] update ML overrides in .eslintrc.js * [ML] yarn.lock symlink * Revert "[ML] yarn.lock symlink" This reverts commit 07f0680 Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
1 parent 1296442 commit 8600a98

40 files changed

+1352
-348
lines changed

‎.eslintrc.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -540,9 +540,15 @@ module.exports = {
540540
* ML overrides
541541
*/
542542
{
543-
files: ['x-pack/legacy/plugins/ml/**/*.js'],
543+
files: ['x-pack/plugins/ml/**/*.js'],
544544
rules: {
545545
'no-shadow': 'error',
546+
'import/no-extraneous-dependencies': [
547+
'error',
548+
{
549+
packageDir: './x-pack',
550+
},
551+
],
546552
},
547553
},
548554

‎packages/kbn-pm/dist/index.js‎

Lines changed: 12 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -42623,28 +42623,21 @@ module.exports = require("tty");
4262342623
const os = __webpack_require__(11);
4262442624
const hasFlag = __webpack_require__(12);
4262542625

42626-
const {env} = process;
42626+
const env = process.env;
4262742627

4262842628
let forceColor;
4262942629
if (hasFlag('no-color') ||
4263042630
hasFlag('no-colors') ||
42631-
hasFlag('color=false') ||
42632-
hasFlag('color=never')) {
42633-
forceColor = 0;
42631+
hasFlag('color=false')) {
42632+
forceColor = false;
4263442633
} else if (hasFlag('color') ||
4263542634
hasFlag('colors') ||
4263642635
hasFlag('color=true') ||
4263742636
hasFlag('color=always')) {
42638-
forceColor = 1;
42637+
forceColor = true;
4263942638
}
4264042639
if ('FORCE_COLOR' in env) {
42641-
if (env.FORCE_COLOR === true || env.FORCE_COLOR === 'true') {
42642-
forceColor = 1;
42643-
} else if (env.FORCE_COLOR === false || env.FORCE_COLOR === 'false') {
42644-
forceColor = 0;
42645-
} else {
42646-
forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
42647-
}
42640+
forceColor = env.FORCE_COLOR.length === 0 || parseInt(env.FORCE_COLOR, 10) !== 0;
4264842641
}
4264942642

4265042643
function translateLevel(level) {
@@ -42661,7 +42654,7 @@ function translateLevel(level) {
4266142654
}
4266242655

4266342656
function supportsColor(stream) {
42664-
if (forceColor === 0) {
42657+
if (forceColor === false) {
4266542658
return 0;
4266642659
}
4266742660

@@ -42675,15 +42668,11 @@ function supportsColor(stream) {
4267542668
return 2;
4267642669
}
4267742670

42678-
if (stream && !stream.isTTY && forceColor === undefined) {
42671+
if (stream && !stream.isTTY && forceColor !== true) {
4267942672
return 0;
4268042673
}
4268142674

42682-
const min = forceColor || 0;
42683-
42684-
if (env.TERM === 'dumb') {
42685-
return min;
42686-
}
42675+
const min = forceColor ? 1 : 0;
4268742676

4268842677
if (process.platform === 'win32') {
4268942678
// Node.js 7.5.0 is the first version of Node.js to include a patch to
@@ -42744,6 +42733,10 @@ function supportsColor(stream) {
4274442733
return 1;
4274542734
}
4274642735

42736+
if (env.TERM === 'dumb') {
42737+
return min;
42738+
}
42739+
4274742740
return min;
4274842741
}
4274942742

‎x-pack/plugins/ml/package.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"author": "Elastic",
3+
"name": "ml",
4+
"version": "0.0.0",
5+
"private": true,
6+
"license": "Elastic-License",
7+
"scripts": {
8+
"build:apiDocScripts": "cd server/routes/apidoc_scripts && tsc",
9+
"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"
10+
},
11+
"devDependencies": {
12+
"apidoc": "^0.20.1",
13+
"apidoc-markdown": "^5.0.0"
14+
}
15+
}

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,14 @@ Each route handler requires [apiDoc](https://github.com/apidoc/apidoc) annotatio
66
to generate documentation.
77
The [apidoc-markdown](https://github.com/rigwild/apidoc-markdown) package is also required in order to generate the markdown.
88

9-
For now the process is pretty manual. You need to make sure the packages mentioned above are installed globally
10-
to execute the following command from the directory in which this README file is located.
9+
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.
10+
11+
Make sure you have run `yarn kbn bootstrap` to get all requires dev dependencies. Then execute the following command from the ml plugin folder:
1112
```
12-
apidoc -i . -o ../routes_doc && apidoc-markdown -p ../routes_doc -o ../routes_doc/ML_API.md
13+
yarn run apiDocs
1314
```
15+
It compiles all the required scripts and generates the documentation both in HTML and Markdown formats.
16+
1417

1518
It will create a new directory `routes_doc` (next to the `routes` folder) which contains the documentation in HTML format
16-
as well as `ML_API.md` file.
19+
as well as `ML_API.md` file.

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

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,8 @@
55
*/
66

77
import Boom from 'boom';
8-
import _ from 'lodash';
98
import { i18n } from '@kbn/i18n';
109

11-
import { schema } from '@kbn/config-schema';
1210
import { SecurityPluginSetup } from '../../../security/server';
1311
import { isAnnotationsFeatureAvailable } from '../lib/check_annotations';
1412
import { annotationServiceProvider } from '../models/annotation_service';
@@ -45,10 +43,7 @@ export function annotationRoutes(
4543
* @apiName GetAnnotations
4644
* @apiDescription Gets annotations.
4745
*
48-
* @apiParam {String[]} jobIds List of job IDs
49-
* @apiParam {String} earliestMs
50-
* @apiParam {Number} latestMs
51-
* @apiParam {Number} maxAnnotations Max limit of annotations returned
46+
* @apiSchema (body) getAnnotationsSchema
5247
*
5348
* @apiSuccess {Boolean} success
5449
* @apiSuccess {Object} annotations
@@ -57,7 +52,7 @@ export function annotationRoutes(
5752
{
5853
path: '/api/ml/annotations',
5954
validate: {
60-
body: schema.object(getAnnotationsSchema),
55+
body: getAnnotationsSchema,
6156
},
6257
},
6358
mlLicense.fullLicenseAPIGuard(async (context, request, response) => {
@@ -83,14 +78,13 @@ export function annotationRoutes(
8378
* @apiName IndexAnnotations
8479
* @apiDescription Index the annotation.
8580
*
86-
* @apiParam {Object} annotation
87-
* @apiParam {String} username
81+
* @apiSchema (body) indexAnnotationSchema
8882
*/
8983
router.put(
9084
{
9185
path: '/api/ml/annotations/index',
9286
validate: {
93-
body: schema.object(indexAnnotationSchema),
87+
body: indexAnnotationSchema,
9488
},
9589
},
9690
mlLicense.fullLicenseAPIGuard(async (context, request, response) => {
@@ -124,17 +118,17 @@ export function annotationRoutes(
124118
/**
125119
* @apiGroup Annotations
126120
*
127-
* @api {delete} /api/ml/annotations/index Deletes annotation
121+
* @api {delete} /api/ml/annotations/delete/:annotationId Deletes annotation
128122
* @apiName DeleteAnnotation
129123
* @apiDescription Deletes specified annotation
130124
*
131-
* @apiParam {String} annotationId
125+
* @apiSchema (params) deleteAnnotationSchema
132126
*/
133127
router.delete(
134128
{
135129
path: '/api/ml/annotations/delete/{annotationId}',
136130
validate: {
137-
params: schema.object(deleteAnnotationSchema),
131+
params: deleteAnnotationSchema,
138132
},
139133
},
140134
mlLicense.fullLicenseAPIGuard(async (context, request, response) => {

0 commit comments

Comments
 (0)