Skip to content

Add Cloud APIs to API Explorer#2893

Draft
lcawl wants to merge 2 commits intomainfrom
docs-builder-apis
Draft

Add Cloud APIs to API Explorer#2893
lcawl wants to merge 2 commits intomainfrom
docs-builder-apis

Conversation

@lcawl
Copy link
Contributor

@lcawl lcawl commented Mar 13, 2026

This PR copies the current Cloud Billing, Cloud ECE, and Cloud Hosted API docs into this repo as a test of the docs in #2879

It proves that the tooling can handle Swagger (OpenAPI v2) documents. Open issues and questions:

  1. How to handle situations where an OpenAPI document doesn't align with a single product ID (e.g. the Cloud Billing APIs) or one that doesn't exist in https://github.com/elastic/docs-builder/blob/main/config/products.yml (e.g. "cloud" or the "observability intake APIs")?
  2. Poor tag names (I believe it's a known issue that this tool doesn't heed the x-displayName values or show the descriptions).

Steps to test

  1. Run docs-builder serve -p /path/to/docs-builder/docs
  2. Wait for messages like this to appear:
    info ::e.a.OpenApiGenerator  :: Generating OpenApiDocument Kibana APIs
    info ::e.a.OpenApiGenerator  :: Generating OpenApiDocument Elastic Cloud Serverless API
    info ::e.a.OpenApiGenerator  :: Generating OpenApiDocument Cloud Billing API
    info ::e.a.OpenApiGenerator  :: Generating OpenApiDocument Elastic Cloud API
    info ::e.a.OpenApiGenerator  :: Generating OpenApiDocument Elastic Cloud Enterprise API
  3. Go to the appropriate URL (matches the keyword added in the docset.yml file). For example: http://localhost:3000/api/cloud-hosted/

Copy link
Member

@Mpdreamz Mpdreamz left a comment

Choose a reason for hiding this comment

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

Great validation! Good to know V2 OpenAPi works as intended in practice too.

For question 2, these will need to be exposed as products in that case (cloud-billing, manager-intake).

We should not embed OpenAPi in git, we should fetch them from our mirror. Some more work is needed to do so.

@lcawl
Copy link
Contributor Author

lcawl commented Mar 13, 2026

For question 2, these will need to be exposed as products in that case (cloud-billing, manager-intake).

This was something I was pondering in the context of release notes as well -- do we need a "cloud" product ID or is it better to be able to apply multiple product Ids to a single item? I think in both the changelogs and APIs the latter is more accurate and clear (i.e. I think these billing APIs apply to both Cloud Serverless and Cloud Hosted but not Cloud Enterprise).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants