[APM] Add documentation for APM APIs

[dannycroft]

In order to provide users with the best and most accurate documentation, all APM app API endpoints must be documented with the OpenAPI specification.

Initial support was added in https://github.com/elastic/kibana/pull/180096, but these are manually generated and incomplete.

We should probably stay as close as possible to the implementation for the SLO APIs: https://github.com/elastic/kibana/tree/main/x-pack/plugins/observability_solution/slo/docs/openapi/slo

Consult with @elastic/obs-ux-management-team to determine observability standards for generating, maintaining, and publishing OpenAPI specs.

✅ Acceptance criteria

• Steps to find and add OpenAPI documentation to a public Kibana API in observability are published (undecided: where? In the observability_solution plugin maybe?)
• APM app API documentation is complete and accurate for all endpoints
• Steps for updating documentation are published (ideally we would want everything automatically updated when we changed the code, but that's not required initially as long as process to update docs is documented and straightforward)
• Notify docs team about availability of specs (@smith is tracking the internal issue to do this)

[elasticmachine]

Pinging @elastic/apm-ui (Team:apm)

[jasonrhodes]

+1 I want this too

[elasticmachine]

Pinging @elastic/obs-ux-infra_services-team (Team:obs-ux-infra_services)

[smith]

The Kibana team has provided guidance and tooling for OpenAPI docs: https://groups.google.com/a/elastic.co/g/kibana-contributors/c/sQunk3FUzA0/m/B1Olq4RhAAAJ?utm_medium=email&utm_source=footer

We might have to consider whether what's provided there will work best with the way we use io-ts, etc., but let's begin the discussion by looking at what they've started.

[jasonrhodes]

Hey @smith -- this is something @maryam-saeidi has been looking into. She'll work with @miltonhultgren who is helping lead the "low level API guidelines" effort via https://docs.google.com/document/d/12AL5ItHs3L9qrWAvIewkvSFJjnly6kOOVhWOVPESSyY/edit

[maryam-saeidi]

FYI, related investigation: OpenAPI Specification (OAS) in Observability