Run api-extractor on non-core plugins

[stacey-gammon]

As a step towards having a consistent documentation system, I'd like to run the api-extractor on non-core plugins, especially those in test/plugin_functional/plugins.

I figured out where the paths are being constructed, and added some to see if it worked on the test plugins, but I get an error:

The "mainEntryPointFilePath" path does not exist: /Users/gammon/Elastic/kibana2/target/test/plugin_functional/plugins/demo_search/public/index.d.ts

I could use some help with next steps.

Another thought is that I don't know if we want this warning about whether an api has been changed everywhere, or just core. Eventually I could see it being useful, but not sure if at this point, it'd be a distraction.

[elasticmachine]

Pinging @elastic/kibana-platform (Team:Platform)

[rudolf]

Another thought is that I don't know if we want this warning about whether an api has been changed everywhere, or just core. Eventually I could see it being useful, but not sure if at this point, it'd be a distraction.

It doesn't need to cause CI to fail, but knowing the API has changed also means your documentation is out of date. Although docs can change without changing the API, this helps keep the documentation consistent until we have an automatic documentation build step (something which we decided to punt for now).

When all the consumers of a Plugin's API's are plugins maintained by Kibana (rather than 3rd party plugins), and they all use typescript, any changes to the type signature of the API will cause typescript errors. If that's the case, having a separate mechanism to detect API type changes doesn't provide much on top of what typescript already provides.

However, for the long term stability of the Kibana ecosystem, it would be really valuable to plugin developers if plugins had a strict process that helped detect changes to ensure that teams document these. So in the long term I think it would be really useful to provide auto-generated docs for plugin API's and let CI fail on API changes that weren't explicitly accepted.

[darnautov]

In ML team we would also like to have consistent documentation system across the codebase, but the most crucial use-case, for now, is RESTful API docs for ML server-side in kibana to share it with other solutions across kibana to make sure they use our endpoints instead of directly querying data from ml ES indices.
The first thing that came to my mind was OpenAPI, but we realized it introduces too many changes to the workflow and decided to give a shot to apiDoc which does the job well for producing markdown files and doesn't require any changes, besides writing the documentation itself 😄 Probably we'll stick to this approach for a while until the platform will provide some further solution with OpenAPI.

[rudolf]

Solved by #56955