github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 09:19:04 -04:00
Code Issues Projects Releases Packages Wiki Activity

[DOCS] Lint ML sync API specification (#148841)

Browse source
This commit is contained in:
Lisa Cawley 2023-01-13 08:44:07 -08:00 • committed by GitHub
parent 852072f41b
commit b174b1908f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 50 additions and 205 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/api-generated/README.md
View file

@ -28,7 +28,7 @@ or a similar tool that can generate HTML output from OAS.
mv $GIT_HOME/kibana/docs/api-generated/rules/index.html $GIT_HOME/kibana/docs/api-generated/rules/rule-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/cases/index.html $GIT_HOME/kibana/docs/api-generated/cases/case-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/connectors/index.html $GIT_HOME/kibana/docs/api-generated/connectors/connector-apis-passthru.asciidoc
mv $GIT_HOME/kibana/docs/api-generated/machine-learning/index.html $GIT_HOME/kibana/docs/api-generated/machine-learning/ml-apis-passthru.adoc
mv $GIT_HOME/kibana/docs/api-generated/machine-learning/index.html $GIT_HOME/kibana/docs/api-generated/machine-learning/ml-apis-passthru.asciidoc
```
. If you're creating a new set of API output, you will need to have a page that incorporates the output by using passthrough blocks. For more information, refer to [Asciidoctor docs](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/)

23
docs/api-generated/machine-learning/ml-apis-passthru.adoc → docs/api-generated/machine-learning/ml-apis-passthru.asciidoc
View file

@ -43,13 +43,13 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">simulate (optional)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> &mdash; When true, simulates the synchronization by returning only the list actions that would be performed. default: null </div>
<div class="param-desc"><span class="param-type">Query Parameter</span> &mdash; When true, simulates the synchronization by returning only the list of actions that would be performed. default: null </div>
</div> <!-- field-items -->
<h3 class="field-label">Return type</h3>
<div class="return-type">
<a href="#mlSyncResponse">mlSyncResponse</a>
<a href="#mlSync200Response">mlSync200Response</a>
</div>
@ -114,7 +114,10 @@ Any modifications made to this file will be overwritten.
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Indicates a successful call
<a href="#mlSyncResponse">mlSyncResponse</a>
<a href="#mlSync200Response">mlSync200Response</a>
<h4 class="field-label">401</h4>
Authorization information is missing or invalid.
<a href="#mlSync4xxResponse">mlSync4xxResponse</a>
</div> <!-- method -->
<hr/>
@ -123,7 +126,8 @@ Any modifications made to this file will be overwritten.
<h3>Table of Contents</h3>
<ol>
<li><a href="#mlSyncResponse"><code>mlSyncResponse</code> - Sync API response</a></li>
<li><a href="#mlSync200Response"><code>mlSync200Response</code> - Successful sync API response</a></li>
<li><a href="#mlSync4xxResponse"><code>mlSync4xxResponse</code> - Unsuccessful sync API response</a></li>
<li><a href="#mlSyncResponseAnomalyDetectors"><code>mlSyncResponseAnomalyDetectors</code> - Sync API response for anomaly detection jobs</a></li>
<li><a href="#mlSyncResponseDataFrameAnalytics"><code>mlSyncResponseDataFrameAnalytics</code> - Sync API response for data frame analytics jobs</a></li>
<li><a href="#mlSyncResponseDatafeeds"><code>mlSyncResponseDatafeeds</code> - Sync API response for datafeeds</a></li>
@ -133,7 +137,7 @@ Any modifications made to this file will be overwritten.
</ol>
<div class="model">
<h3><a name="mlSyncResponse"><code>mlSyncResponse</code> - Sync API response</a> <a class="up" href="#__Models">Up</a></h3>
<h3><a name="mlSync200Response"><code>mlSync200Response</code> - Successful sync API response</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">datafeedsAdded (optional)</div><div class="param-desc"><span class="param-type"><a href="#mlSyncResponseDatafeeds">map[String, mlSyncResponseDatafeeds]</a></span> If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API. </div>
@ -142,6 +146,15 @@ Any modifications made to this file will be overwritten.
<div class="param">savedObjectsDeleted (optional)</div><div class="param-desc"><span class="param-type"><a href="#mlSyncResponseSavedObjectsDeleted">mlSyncResponseSavedObjectsDeleted</a></span> </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="mlSync4xxResponse"><code>mlSync4xxResponse</code> - Unsuccessful sync API response</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">error (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> </div>
<div class="param">message (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> </div>
<div class="param">statusCode (optional)</div><div class="param-desc"><span class="param-type"><a href="#integer">Integer</a></span> </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="mlSyncResponseAnomalyDetectors"><code>mlSyncResponseAnomalyDetectors</code> - Sync API response for anomaly detection jobs</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.</div>

2
docs/api-generated/machine-learning/ml-apis.asciidoc
View file

@ -7,4 +7,4 @@ preview::[]
This file includes content that has been generated from https://github.com/elastic/kibana/tree/main/x-pack/plugins/ml/common/openapi. Any modifications required must be done in that open API specification.
////
include::ml-apis-passthru.adoc[]
include::ml-apis-passthru.asciidoc[]

6
x-pack/plugins/ml/common/openapi/README.md
View file

@ -4,14 +4,14 @@ The current self-contained spec file can be used for online tools like those fou
A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
The `ml_apis_v2.json` file uses OpenAPI Specification Version 2.0.
The `ml_apis_v3.yaml` file uses OpenAPI Specification Version 3.0.1.
## Tools
It is possible to validate the docs before bundling them by running the following command in the `x-pack/plugins/ml/common/openapi/` folder:
It is possible to validate the docs before bundling them by running these
commands in the `x-pack/plugins/ml/common/openapi/` folder:
```
npx swagger-cli validate ml_apis_v2.json
npx swagger-cli validate ml_apis_v3.yaml
npx @redocly/cli lint ml_apis_v3.yaml
```

185
x-pack/plugins/ml/common/openapi/ml_apis_v2.json
View file

@ -1,185 +0,0 @@
{
"swagger" : "2.0",
"info" : {
"version" : "1",
"title" : "Machine learning APIs",
"description": "Kibana APIs for the machine learning feature",
"termsOfService" : "",
"license": {
"name": "Elastic License 2.0",
"url": "https://www.elastic.co/licensing/elastic-license"
}
},
"host" : "localhost:5601",
"basePath" : "/",
"tags" : [ {
"name" : "ml",
"description": "Machine learning"
} ],
"schemes" : [ "https" ],
"security" : [
{
"basicAuth": [ ]
},
{
"apiKey" : [ ]
}
],
"paths" : {
"/s/{spaceId}/api/ml/saved_objects/sync" : {
"get" : {
"tags" : [ "ml" ],
"summary" : "Sync machine learning objects",
"description" : "Synchronizes Kibana saved objects for machine learning jobs and trained models. You must have `all` privileges for the **Machine Learning** feature in the **Analytics** section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.",
"operationId" : "ml-sync",
"parameters" : [ {
"name" : "spaceId",
"in" : "path",
"description" : "An identifier for the space. If you omit `/s/` and this identifier from the path, the default space is used.",
"required" : true,
"type" : "string"
}, {
"name" : "simulate",
"in" : "query",
"description" : "When true, simulates the synchronization by returning only the list actions that would be performed.",
"required" : false,
"type" : "boolean",
"default" : false
} ],
"responses" : {
"200" : {
"description" : "Indicates a successful call.",
"schema" : {
"$ref" : "#/definitions/MLSyncResponse"
}
}
},
"x-doc" : {
"tag" : "Machine learning APIs"
}
}
}
},
"securityDefinitions" : {
"apiKey" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header"
},
"basicAuth": {
"type": "basic"
}
},
"definitions": {
"MLSyncResponse-Datafeeds": {
"type": "object",
"description": "The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.",
"properties" : {
"success": {
"type" : "boolean",
"description": "The success or failure of the synchronization."
}
}
},
"MLSyncResponse-Jobs": {
"type": "object",
"description": "The sync machine learning saved objects API response contains this object when there are machine learning jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.",
"properties": {
"success": {
"type" : "boolean",
"description": "The success or failure of the synchronization."
}
}
},
"MLSyncResponse-Models": {
"type": "object",
"description": "The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.",
"properties": {
"success": {
"type" : "boolean",
"description": "The success or failure of the synchronization."
}
}
},
"MLSyncResponse-SavedObjectsCreated":{
"type": "object",
"description": "If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.",
"properties": {
"anomaly-detector": {
"type": "object",
"description": "This object is present if there are anomaly detection jobs affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Jobs"
}
},
"data-frame-analytics": {
"type": "object",
"description": "This object is present if there are data frame analytics jobs affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Jobs"
}
},
"trained-model": {
"type": "object",
"description": "This object is present if there are trained models affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Models"
}
}
}
},
"MLSyncResponse-SavedObjectsDeleted":{
"type": "object",
"description": "If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.",
"properties": {
"anomaly-detector": {
"type": "object",
"description": "This object is present if there are anomaly detection jobs affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Jobs"
}
},
"data-frame-analytics": {
"type": "object",
"description": "This object is present if there are data frame analytics jobs affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Jobs"
}
},
"trained-model": {
"type": "object",
"description": "This object is present if there are trained models affected by the synchronization.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Models"
}
}
}
},
"MLSyncResponse": {
"type": "object",
"description": "The sync machine learning saved objects API returns this list of machine learning saved objects that required synchronization.",
"properties": {
"savedObjectsCreated": {
"$ref" : "#/definitions/MLSyncResponse-SavedObjectsCreated"
},
"savedObjectsDeleted": {
"$ref" : "#/definitions/MLSyncResponse-SavedObjectsDeleted"
},
"datafeedsAdded": {
"type": "object",
"description": "If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API.",
"additionalProperties":{
"$ref" : "#/definitions/MLSyncResponse-Datafeeds"
}
},
"datafeedsRemoved": {
"type": "object",
"description": "If a saved object for an anomaly detection job references a datafeed that no longer exists, it is deleted when you run the sync machine learning saved objects API.",
"additionalProperties": {
"$ref" : "#/definitions/MLSyncResponse-Datafeeds"
}
}
}
}
}
}

37
x-pack/plugins/ml/common/openapi/ml_apis_v3.yaml
View file

@ -10,7 +10,7 @@ tags:
- name: ml
description: Machine learning
servers:
- url: https://localhost:5601/
- url: https://localhost:5601
paths:
/s/{spaceId}/api/ml/saved_objects/sync:
get:
@ -30,10 +30,16 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/mlSyncResponse'
$ref: '#/components/schemas/mlSync200Response'
examples:
syncExample:
$ref: '#/components/examples/mlSyncExample'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/mlSync4xxResponse'
components:
parameters:
spaceParam:
@ -131,9 +137,9 @@ components:
properties:
success:
$ref: '#/components/schemas/mlSyncResponseSuccess'
mlSyncResponse:
mlSync200Response:
type: object
title: Sync API response
title: Successful sync API response
properties:
datafeedsAdded:
type: object
@ -149,21 +155,32 @@ components:
$ref: '#/components/schemas/mlSyncResponseSavedObjectsCreated'
savedObjectsDeleted:
$ref: '#/components/schemas/mlSyncResponseSavedObjectsDeleted'
mlSync4xxResponse:
type: object
title: Unsuccessful sync API response
properties:
error:
type: string
example: Unauthorized
message:
type: string
statusCode:
type: integer
example: 401
examples:
mlSyncExample:
summary: Two anomaly detection jobs required synchronization in this example.
value:
{
"savedObjectsCreated": {
"anomaly_detector": {
"anomaly-detector": {
"myjob1": { "success":true },
"myjob2":{ "success":true }
"myjob2": { "success":true }
}
},
"savedObjectsDeleted": {},
"datafeedsAdded":{},
"datafeedsRemoved":{}
"datafeedsAdded": {},
"datafeedsRemoved": {}
}
security:
- basicAuth: [ ]
- ApiKeyAuth: [ ]
- basicAuth: [ ]