You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
🚀 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 #2482Those examples will be incorporated into the
schema.json
and OpenAPI output per #3737If 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:
For example: https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-exists.html
In the new API documentation, it looks like this:
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.
The text was updated successfully, but these errors were encountered: