Skip to content

[ML] Replace apiDoc annotations with routes definitions for OpenAPI spec generation #190840

Merged
darnautov merged 21 commits intoelastic:mainfrom
darnautov:ml-apidocs-to-openapi
Aug 23, 2024
Merged

[ML] Replace apiDoc annotations with routes definitions for OpenAPI spec generation #190840
darnautov merged 21 commits intoelastic:mainfrom
darnautov:ml-apidocs-to-openapi

Conversation

@darnautov
Copy link
Copy Markdown
Contributor

@darnautov darnautov commented Aug 20, 2024

Summary

  • Removes apidoc-markdown dependency and custom scripts for generating internal documentation for ML Kibana endpoints
  • Replaces apidoc annotations with summary and description props for route handlers and kbn-schemas to generate an OpenAPI spec file
  • /internal/ml/jobs/delete_jobs route was not versioned for some reason, I changed that

How to test

  1. Enable OAS endpoint in kibana.dev.yml
server.oas.enabled: true
  1. Start Kibana dev server
yarn start --no-base-path
  1. Call the OAS endpoint for ML internal routes
curl -s -u <USERNAME>:<PASSWORD> http://localhost:5601/api/oas\?pathStartsWith\=/internal/ml\&access\=internal -o ml_kibana_openapi.json

@darnautov darnautov marked this pull request as ready for review August 21, 2024 12:33
@darnautov darnautov requested a review from a team as a code owner August 21, 2024 12:33
@darnautov darnautov self-assigned this Aug 21, 2024
@darnautov darnautov added :ml release_note:skip Skip the PR/issue when compiling release notes Team:ML Team label for ML (also use :ml) t// v8.16.0 labels Aug 21, 2024
@elasticmachine
Copy link
Copy Markdown
Contributor

Pinging @elastic/ml-ui (:ml)

* @apiSchema (params) recognizeModulesSchema
* @apiSchema (query) moduleFilterSchema
* @apiSuccess {object[]} modules Array of objects describing the modules which match the index pattern, sorted by module ID.
* @apiSuccessExample {json} Success-Response:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What sort of info will be displayed now for an example response like this? Just wondering as these examples from the modules route are quite rich in information in showing you the structure of a module.

@darnautov
Copy link
Copy Markdown
Contributor Author

@elasticmachine merge upstream

@walterra
Copy link
Copy Markdown
Contributor

It looks like some auto-formatting in renovate.json kicked in that changed the whole file, do you want to update it like that or keep the changes to what's actually been updated?

@darnautov
Copy link
Copy Markdown
Contributor Author

It looks like some auto-formatting in renovate.json kicked in that changed the whole file, do you want to update it like that or keep the changes to what's actually been updated?

thx @walterra, fixed in 89471ef

Copy link
Copy Markdown
Contributor

@walterra walterra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I was able to follow the setup steps and call the oas endpoint.

Copy link
Copy Markdown
Contributor

@peteharverson peteharverson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Great work setting this up!

@darnautov darnautov enabled auto-merge (squash) August 23, 2024 11:37
@kibana-ci
Copy link
Copy Markdown

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

  • [job] [logs] x-pack/test_serverless/functional/test_suites/observability/common_configs/config.group6.ts / context app context link in discover should open the context view with the selected document as anchor and allows selecting next anchor
  • [job] [logs] FTR Configs #90 / dashboard app - group 5 embed mode default URL params renders as expected
  • [job] [logs] FTR Configs #35 / discover/group5 discover URL state should merge custom global filters with saved search filters
  • [job] [logs] FTR Configs #2 / maps app documents source search hits layer query should apply layer query to fit to bounds
  • [job] [logs] FTR Configs #22 / Visualizations - Group 2 lens app - Agg based Vis Open in Lens Goal should convert color ranges
  • [job] [logs] FTR Configs #23 / Visualizations - Group 2 lens app - Agg based Vis Open in Lens Goal should convert color ranges
  • [job] [logs] FTR Configs #92 / Visualizations - Group 2 lens app - Agg based Vis Open in Lens Goal should convert color ranges

Metrics [docs]

Unknown metric groups

ESLint disabled line counts

id before after diff
ml 553 550 -3

Total ESLint disabled count

id before after diff
ml 556 553 -3

History

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @darnautov

@darnautov darnautov merged commit f9c43f6 into elastic:main Aug 23, 2024
@kibanamachine kibanamachine added the backport:skip This PR does not require backporting label Aug 23, 2024
@darnautov darnautov deleted the ml-apidocs-to-openapi branch August 23, 2024 14:11
darnautov added a commit that referenced this pull request Aug 30, 2024
## Summary

Fixes an issue introduced in
#190840 where the module endpoint
had a wrong type definition for validation the response causing the
Rules page in Security plugin to crash.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport:skip This PR does not require backporting :ml release_note:skip Skip the PR/issue when compiling release notes Team:ML Team label for ML (also use :ml) t// v8.16.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants