DOC-13663: Improve process for Search and Query REST API examples

[simon-dew]

Jira issue: DOC-13663

• Follows on from DOC-13663: Fix process for Search and Query REST API examples #195

This PR revisits requirement 2 of the Jira ticket, "Make sure the static REST API references get their examples from the dev repos". Now that we have migrated to Handlebars, it is possible to bundle the examples into the spec using the Redocly CLI, and then build the examples into the generated AsciiDoc automatically. This enables us to get rid of many superfluous example files that were being copied to this repo, and the partials which included those example files.

As part of this I have also updated the templates to look for curl-request.adoc partials in the {snippetDir}, in addition to http-request.adoc and http-response.adoc partials.

• curl-request.adoc partials are now used for command line request examples using curl.
• http-request.adoc partials are now used for request body examples.
• http-response.adoc partials are still used for response body examples.

I chose these partials for compatibility with the Spring REST Docs snippets expected by Swagger2Markup, even though they are not strictly in line with the Default Snippets generated by Spring REST Docs.

I have tweaked the functionality of these snippets so that if examples are present in the spec, the snippet text is included after the automatically-generated example title, but before the example itself. This enables you to use the snippets (without header) to add a commentary or extra information to the example. If there is no example present in the spec, you can use the snippet to add an entire example (with header) as previously.

There are still some example files and partials remaining in this repo for the Query REST APIs. That's because we need to further refine the spec upstream to include shell script and / or body text examples. See DOC-13976.

[Copilot]

Pull request overview

This PR improves the process for generating REST API documentation by bundling examples directly from OpenAPI specifications using the Redocly CLI, eliminating the need to fetch and maintain separate example files in the repository.

Changes:

• Replaced example file fetching tasks with Redocly bundling tasks in Gradle build files
• Updated Handlebars templates to automatically generate examples from bundled specifications
• Removed obsolete example files and partials that are now generated automatically

Reviewed changes

Copilot reviewed 161 out of 239 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
templates/*.handlebars	New templates for rendering request/response examples from spec data
templates/index.handlebars	Enhanced to generate examples automatically and support curl-request snippets
templates/param.handlebars	Added fallback to description field
docs/modules/*/*.gradle	Replaced getExamples tasks with bundleSpec tasks using Redocly CLI
docs/modules/*/partials/header-attributes.adoc	Added :!example-caption: attribute
docs/modules//partials/paths/*/http-.adoc	Removed or simplified partials now handled by templates
docs/modules/*/pages/index.adoc	Regenerated with embedded examples from specs
docs/modules/*/examples/*.json, *.sh	Removed example files now bundled from upstream

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.