Skip to content

Add API examples in multiple languages #3915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lcawl opened this issue Mar 7, 2025 · 0 comments
Open

Add API examples in multiple languages #3915

lcawl opened this issue Mar 7, 2025 · 0 comments

Comments

@lcawl
Copy link
Contributor

lcawl commented Mar 7, 2025

🚀 Feature Proposal

Relates to elastic/docs-builder#55, but specifically in the automated API docs context.

In the old documentation system, we enabled users to copy examples in multiple languages. From a quick test, it seems like we can do the same in Bump.sh by using x-codeSamples.

The outstanding work IMO would be to (1) talk to @miguelgrinberg about the feasibility of using existing converter tools to generate these variations from our examples, then (2) investigate whether the automation @siamakp-elastic added for incorporating the request and response body examples could be extended to add these x-codeSamples too. From a brief conversation with @miguelgrinberg it seemed like perhaps these language-specific examples could be generated as part of the pipeline for generating the OpenAPI (i.e. they wouldn't necessarily need to be checked into the repo anywhere).

Motivation

API examples have been copied into this elasticsearch-specification repo from the Elasticsearch documentation per #2482
Those examples will be incorporated into the schema.json and OpenAPI output per #3737

If there is still "demand for more extensive examples for language clients" and "these auto-generated API request examples [are still seen] as a great way to fulfill this customer request" per elastic/docs-builder#55 (comment) then this seems like a pretty good next step for our API docs.

Example

In the old API documentation, the language selector looked like this:

Image

For example: https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-exists.html

In the new API documentation, it looks like this:

Image

For example: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-exists

This proof of concept used the following files: https://github.com/elastic/elasticsearch-specification/tree/main/specification/_global/exists/examples/xCodeSamples
... which are applied to the OpenAPI via an overlay in https://github.com/elastic/elasticsearch-specification/blob/main/docs/overlays/elasticsearch-shared-overlays.yaml but the longer-term solution should not rely on fragile overlays.

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

No branches or pull requests

1 participant