DOC-14157: Public specs for the Service REST APIs by simon-dew · Pull Request #209 · couchbaselabs/cb-swagger

simon-dew · 2026-03-24T15:10:18Z

Jira issue: DOC-14157

This PR does two things:

Makes sure that a downloadable, filtered, and bundled spec is available for each REST API in the attachments directory
Adds service-desc and service-desc-type attributes to each output page, pointing to the spec

Preview URL: REST API reference — the Service REST API pages should appear unchanged.

You will need the Docs Team credentials on Confluence.

Design Principles

Downloadable specs must be publicly available in the attachments directory for the relevant page, so that the user (or an LLM) can access them.
Downloadable specs will have a unique name reflecting the content of the spec and the processes that have been applied to it, e.g. search-advanced.bundle.yaml or eventing.overlaid.yaml.
All source files or overlay files which:
1. affect the build of the downloadable REST API spec,
2. the writers need to edit,
3. but users and LLMs should not be able to access,
are stored in the attachments directory with a name beginning with an underscore, so that they are not published by Antora.
All source files or intermediate files which:
1. affect the build of the downloadable REST API spec,
2. the writers do not need to edit,
3. and users and LLMs should not be able to access,
are stored in the builds directory, which is ignored by Antora and git — see .gitignore.

Changes

For the Analytics and Index REST APIs, pretty much no changes needed to be made, other than tidying up the gradle build scripts to use gradle variables and eliminate repetition.

For the Search and Query REST APIs, the gradle scripts use the redocly CLI via an NpxTask to bundle the remote spec, because the redocly CLI is the only bundler that deferences example files.

The Eventing REST API is a special case. It uses an openapi-generator task to bundle the initial spec, because Redocly CLI has a hard time incorporating external JSON schema files. It then uses the jayOverlay task to apply an OpenAPI overlay to the bundled spec. The jayOverlay task does not allow you to change the name of the output file, so asks.applyOverlay.doLast uses a built-in Ant task to rename the output file to fit in with our schema.

pass file name to generator

source spec should be hidden

Copilot

Pull request overview

This PR updates the REST API reference build so each Service REST API page can point to a publicly downloadable OpenAPI spec (published under the page’s _attachments/), and adjusts module Gradle builds to generate/write those bundled specs into the attachments directories.

Changes:

Add :service-desc: and :service-desc-type: page attributes via the shared Handlebars template (and corresponding per-module serviceDesc values in Gradle).
Update per-module Gradle builds to output bundled specs into attachments/ and generate pages under each module’s pages/ directory.
Add/update bundled OpenAPI YAML artifacts for multiple services (Query, Search, etc.) in module attachments/.

Reviewed changes

Copilot reviewed 48 out of 49 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
templates/index.handlebars	Adds `service-desc` / `service-desc-type` attributes to generated pages.
docs/modules/n1ql-rest-settings/query-settings.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/n1ql-rest-settings/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/n1ql-rest-settings/attachments/query-settings.bundle.yaml	Adds downloadable bundled spec for Query Settings API.
docs/modules/n1ql-rest-query/query-service.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/n1ql-rest-query/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/n1ql-rest-query/attachments/query-service.bundle.yaml	Adds downloadable bundled spec for Query Service API.
docs/modules/n1ql-rest-functions/functions.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/n1ql-rest-functions/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/n1ql-rest-functions/attachments/functions.bundle.yaml	Adds downloadable bundled spec for Query Functions API.
docs/modules/n1ql-rest-admin/admin.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/n1ql-rest-admin/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/index-rest-stats/indexes.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/index-rest-stats/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/fts-rest-stats/search-stats.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-stats/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-stats/attachments/search-stats.bundle.yaml	Adds downloadable bundled spec for Search Stats API.
docs/modules/fts-rest-query/search-query.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-query/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-query/attachments/search-query.bundle.yaml	Adds downloadable bundled spec for Search Active Queries API.
docs/modules/fts-rest-nodes/search-nodes.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-nodes/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-nodes/attachments/search-nodes.bundle.yaml	Adds downloadable bundled spec for Search Node API.
docs/modules/fts-rest-manage/search-manage.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-manage/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-manage/attachments/search-manage.bundle.yaml	Adds downloadable bundled spec for Search Manager Options API.
docs/modules/fts-rest-indexing/search-index.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-indexing/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-advanced/search-advanced.gradle	Bundles remote spec into `attachments/` and passes `serviceDesc` to generator.
docs/modules/fts-rest-advanced/pages/index.adoc	Adds `service-desc` metadata pointing to bundled spec.
docs/modules/fts-rest-advanced/attachments/search-advanced.bundle.yaml	Adds downloadable bundled spec for Search Advanced API.
docs/modules/eventing-rest-api/eventing.gradle	Updates bundling/overlay pipeline and passes `serviceDesc` for overlaid spec.
docs/modules/eventing-rest-api/pages/index.adoc	Adds `service-desc` metadata pointing to overlaid spec.
docs/modules/eventing-rest-api/attachments/_eventing.yaml	Adds hidden source spec for Eventing bundling/overlay pipeline.
docs/modules/analytics-rest-settings/analytics-settings.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-settings/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/analytics-rest-service/analytics-service.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-service/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/analytics-rest-links/analytics-links.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-links/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/analytics-rest-library/analytics-library.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-library/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/analytics-rest-config/analytics-config.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-config/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.
docs/modules/analytics-rest-admin/analytics-admin.gradle	Normalizes paths and passes `serviceDesc` for published spec.
docs/modules/analytics-rest-admin/pages/index.adoc	Adds `service-desc` metadata pointing to published spec.

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

simon-dew · 2026-03-24T15:24:12Z

@osfameron I don't see the service-desc metadata in the output HTML files — has this change been incorporated into the preview builds yet? Or am I doing something wrong?

simon-dew · 2026-03-24T16:27:47Z

@osfameron I don't see the service-desc metadata in the output HTML files — has this change been incorporated into the preview builds yet? Or am I doing something wrong?

Rebuilt preview

osfameron

The link rel is now correctly shown in the preview, and the relative link resolves to the attached file.

I've not reviewed the .gradle configs, if you'd like a review, then let's arrange a quick call to discuss (as I don't really understand gradle myself 😱)

* Standardize spec file names; pass file name to generator * Include service-desc in page attributes * Use ${projectDir} in build scripts * Fix eventing: source spec should be hidden * Update gradle builds to use project name * Build output documentation

osfameron · 2026-03-25T10:24:03Z

    generatorName = "asciidoc"
-    inputSpec = file("attachments/analytics-admin.yaml").getAbsolutePath().toString()
-    outputDir = "${rootDir}/docs/modules/analytics-rest-admin/pages"
+    inputSpec = file("attachments/${project.name}.yaml").getAbsolutePath().toString()


it looks like ${project.name} still resolves to analytics-admin, is that correct?
there's nothing in gradle.properties, so I guess it's extracted from the name of e.g. analytics-admin.gradle.

So this change is just to make the script easy to drop-in to other directories?

Ah sorry I merged the PR before I saw this. ${project.name} resolves to the project name (of course), which is taken from settings.gradle. It does have the advantage of making the script easier to drop into other directories, but the main reason for the switch is because the project name is used multiple times in each script¹ and I wanted to use a single source of truth and reduce the chance of copy-paste errors.

Footnotes

This isn't so obvious in the Analytics build scripts but it becomes more obvious in the Query, Search, and Eventing build scripts ↩

osfameron

Looks sensible to me - I see the analytics-*/*.gradle files are functionally identical for example, while the other categories have some modifications with Overlays.

* Standardize spec file names; pass file name to generator * Include service-desc in page attributes * Use ${projectDir} in build scripts * Fix eventing: source spec should be hidden * Update gradle builds to use project name * Build output documentation

* Standardize spec file names; pass file name to generator * Include service-desc in page attributes * Use ${projectDir} in build scripts * For Capella, output specs should not be published * Update gradle builds to use project name * Build output documentation

simon-dew added 6 commits March 23, 2026 21:19

Standardize spec file names;

0c88d1e

pass file name to generator

Include service-desc in page attributes

f841427

Use ${projectDir} in build scripts

bf1d979

Fix eventing:

add0217

source spec should be hidden

Update gradle builds to use project name

0f19923

Build output documentation

fc8b984

simon-dew requested review from Copilot and osfameron March 24, 2026 15:10

Copilot started reviewing on behalf of simon-dew March 24, 2026 15:12 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Comment thread docs/modules/eventing-rest-api/eventing.gradle Outdated

simon-dew added 2 commits March 24, 2026 16:59

Updates after review

c760f42

Rebuild output

0474e48

osfameron approved these changes Mar 24, 2026

View reviewed changes

simon-dew merged commit fecbacc into release/7.6 Mar 25, 2026
1 check passed

simon-dew deleted the DOC-14157-llm-readiness branch March 25, 2026 09:56

osfameron reviewed Mar 25, 2026

View reviewed changes

osfameron approved these changes Mar 25, 2026

View reviewed changes

This was referenced Mar 31, 2026

DOC-14186: Public spec for the Sync Gateway REST APIs couchbase/docs-sync-gateway#962

Merged

DOC-14186: Public spec for the Sync Gateway REST APIs couchbase/docs-sync-gateway#963

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC-14157: Public specs for the Service REST APIs#209

DOC-14157: Public specs for the Service REST APIs#209
simon-dew merged 8 commits into
release/7.6from
DOC-14157-llm-readiness

simon-dew commented Mar 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

simon-dew commented Mar 24, 2026

Uh oh!

simon-dew commented Mar 24, 2026

Uh oh!

osfameron left a comment

Uh oh!

Uh oh!

osfameron Mar 25, 2026

Uh oh!

simon-dew Mar 25, 2026 •

edited

Loading

Uh oh!

osfameron left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

simon-dew commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design Principles

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

simon-dew commented Mar 24, 2026

Uh oh!

simon-dew commented Mar 24, 2026

Uh oh!

osfameron left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

osfameron Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

simon-dew Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

osfameron left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

simon-dew commented Mar 24, 2026 •

edited

Loading

simon-dew Mar 25, 2026 •

edited

Loading