Skip to content

Only add x-codeSamples extensions to docs builds of openapi #4582

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

Merged
merged 1 commit into from
Jun 17, 2025

Conversation

miguelgrinberg
Copy link
Contributor

@miguelgrinberg miguelgrinberg commented Jun 16, 2025

This change moves the generation of the x-codeSamples OpenAPI extension to the docs-specific builds. The make transform-to-openapi-for-docs reruns the request converter on all examples, then regenerates schema.json so that the new examples are included. Then it calls the OpenAPI generator with the new --include-language-examples option to request that the x-codeSamples extension is included.

The regular OpenAPI builds do not include the new CLI option, so they will not have x-codeSamples. The make generate command does not regenerate examples anymore, since this is only needed for the docs workflow now.

In addition to the above, the generate-language-examples.js script was changed so that it performs a non-destructive update of the language examples. This is to allow code examples for other languages with no request converter support to be added manually, or through custom builds of the request converter, such as the one supporting Java.

@miguelgrinberg miguelgrinberg force-pushed the move-x-code-samples-to-docs-build branch from 68cab92 to fb9be3e Compare June 17, 2025 13:29
@miguelgrinberg miguelgrinberg merged commit 688cb34 into main Jun 17, 2025
8 checks passed
@miguelgrinberg miguelgrinberg deleted the move-x-code-samples-to-docs-build branch June 17, 2025 13:37
Copy link
Contributor

The backport to 9.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-4582-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 688cb3447d94699a50f1ca5b89324caf922e11d5
# Push it to GitHub
git push --set-upstream origin backport-4582-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0

Then, create a pull request where the base branch is 9.0 and the compare/head branch is backport-4582-to-9.0.

miguelgrinberg added a commit that referenced this pull request Jun 18, 2025
* Add request details to examples (#4445)

* add request heading line to request examples

* add request heading line to response examples

* changes to the compiler to include the request heading

* add example requests for endpoints that do not use bodies (#4489)

* add a few example requests for endpoints that do not use bodies

* Remove x-codeSamples from overlay

* restructure existing examples w/o bodies as request examples

* skip examples w/o bodies when generating openapi examples

* add a lot of missing examples

* remove duplicate test

* more examples missed in previous commit

---------

Co-authored-by: lcawl <lcawley@elastic.co>

* add language client examples to YAML files (#4514)

* expand model to include language versions of examples

* add language client examples to YAML files

* use $ELASTICSEARCH_URL in curl examples

* remove unnecessary generate-language-examples task from the openapi generation

* upgrade request converter to latest

* Only add x-codeSamples extensions to docs builds of openapi (#4582)

* address example errors

---------

Co-authored-by: lcawl <lcawley@elastic.co>
miguelgrinberg added a commit that referenced this pull request Jun 18, 2025
* Add request details to examples (#4445)

* add request heading line to request examples

* add request heading line to response examples

* changes to the compiler to include the request heading

* add example requests for endpoints that do not use bodies (#4489)

* add a few example requests for endpoints that do not use bodies

* Remove x-codeSamples from overlay

* restructure existing examples w/o bodies as request examples

* skip examples w/o bodies when generating openapi examples

* add a lot of missing examples

* remove duplicate test

* more examples missed in previous commit

---------

Co-authored-by: lcawl <lcawley@elastic.co>

* add language client examples to YAML files (#4514)

* expand model to include language versions of examples

* add language client examples to YAML files

* use $ELASTICSEARCH_URL in curl examples

* remove unnecessary generate-language-examples task from the openapi generation

* upgrade request converter to latest

* Only add x-codeSamples extensions to docs builds of openapi (#4582)

* address example errors

---------

Co-authored-by: lcawl <lcawley@elastic.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants