Skip to content

[Markdowns API] Polish OAS docs and co-locate examples with route code#1

Closed
florent-leborgne wants to merge 6 commits into
as-code/public-markdown-apifrom
asCode/polish-markdown-api
Closed

[Markdowns API] Polish OAS docs and co-locate examples with route code#1
florent-leborgne wants to merge 6 commits into
as-code/public-markdown-apifrom
asCode/polish-markdown-api

Conversation

@florent-leborgne

@florent-leborgne florent-leborgne commented May 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

Polishes the public Markdowns API OpenAPI documentation and brings it in line with the conventions used by the dashboards and visualizations APIs.

Note: this PR is hosted on florent-leborgne/kibana because the parent branch as-code/public-markdown-api only exists on cqliu1/kibana, not on elastic/kibana. Once cqliu1's parent branch lands upstream, these commits can be retargeted to elastic/kibana as-is.

What the PR does

Markdowns API source code

  • Each public route (POST, GET search, GET by ID, PUT, DELETE) carries a concrete per-operation description instead of the generic technical-preview boilerplate from commonRouteConfig.
  • The content, settings, and settings.open_links_in_new_tab schema fields all have meta.description. The content description spells out that it's GitHub-flavored Markdown and lists the supported elements.
  • The id path parameter on GET by ID, DELETE, and PUT uses the same phrasing as the dashboards API: The markdown library item ID, as returned by the create or search endpoints.
  • The OAS tag is Markdowns (PascalCase, plural), matching Dashboards and Visualizations.

Examples and code samples co-located with the routes

src/platform/plugins/shared/dashboard_markdown/server/api/oas_examples.ts defines the typed example payloads, cURL and Console code samples, and operation-level descriptions for all five endpoints. The five exported operation objects are lazy-imported by each register_*_route.ts via addVersion({ options: { oasOperationObject } }), following the pattern introduced for the dashboards and visualizations APIs in elastic#270181.

Example payloads are typed with satisfies against the schema-derived response types, so a schema change that breaks an example fails the build. Request bodies are defined once and reused as data in the response examples, so they can't drift.

OAS overlays

  • oas_docs/overlays/markdowns.overlays.yaml provides the tag-level narrative: when to use the API, how to authenticate, how to reference a library item from a dashboard, plus externalDocs pointing at the Text panels page and the Markdowns display name. Operation-level examples and code samples are not here, they come from TypeScript.
  • oas_docs/overlays/kibana.overlays.bump_slim.yaml gives the Markdowns API the same technical-preview redirect treatment as the dashboards and visualizations APIs: in the public Bump bundle (kibana.yaml), each operation collapses to a notice linking to the external full reference at elastic.github.io/dashboards-api-spec. The full spec still ships through kibana.external.yaml.
  • oas_docs/overlays/kibana.overlays.strip_request_examples.yaml strips Markdowns requestBody.examples from the external bundle alongside the dashboards and visualizations entries (same temporary workaround until the external renderer handles requestBody.examples natively).
  • oas_docs/makefile wires the new overlay into both the standard and external pipelines.

Dependencies and limitations

florent-leborgne and others added 6 commits May 27, 2026 15:35
@florent-leborgne @cursoragent
Polish markdown library item API spec metadata
944fa7d 
Aligns the markdown library item API with the conventions used by the
dashboards and visualizations APIs:

- Override the technical-preview boilerplate description on POST, GET
  by ID, PUT, and DELETE with concrete per-operation descriptions
  (the shared description in commonRouteConfig was used as-is on every
  non-search route, so the rendered docs showed the preview disclaimer
  in place of the operation description).
- Rename the OAS tag from `markdown` (lowercase, singular) to
  `Markdowns` (PascalCase, plural) to match `Dashboards` and
  `Visualizations`.
- Add descriptions to `content`, `settings`, and
  `settings.open_links_in_new_tab` in the markdown embeddable state
  schema. These fields are spread into the API's request and response
  bodies and were previously undocumented.
- Use the same phrasing as the dashboards API for the `id` path
  parameter on GET by ID and DELETE.

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne @cursoragent
oas_docs: add markdowns overlay (tag description, examples, code samp…
5449615 
…les)

Mirrors what dashboards.overlays.yaml and visualizations.overlays.yaml
do for their respective tags:

- A tag-level description for `Markdowns` with intro, when-to-use
  guidance, get-started block, and a brief reference to the dashboards
  panel `ref_id` pattern for cross-discoverability.
- Minimal request body and response examples on POST, GET list, GET
  by ID, and PUT operations. This also clears the `kbn-validate-oas`
  errors that complained about missing `examples` on every markdowns
  content body.
- cURL and Console code samples on every operation, so the rendered
  docs have a runnable snippet in the right-hand column.

Wires the new overlay into the standard pipeline (between
visualizations and bump-slim) and into the external pipeline (between
visualizations and strip_request_examples). The strip overlay is
extended to also drop the markdowns POST and PUT request examples in
the external render, to match the existing dashboards/visualizations
handling.

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne @cursoragent
Move Markdowns API examples and code samples next to the route code
b9216eb 
Mirrors the pattern introduced for the Dashboards and Visualizations APIs in
elastic#270181: typed example bodies, code samples, descriptions, and
the assembled OAS operation objects now live in
`server/api/oas_examples.ts`, alongside the route definitions that consume
them via `addVersion({ options: { oasOperationObject } })`.

The post-processing overlay (`oas_docs/overlays/markdowns.overlays.yaml`) is
trimmed to tag-level narrative (getting-started content, externalDocs, display
name). Operation-level examples and code samples no longer have to be
maintained in a separate YAML layer.

Also fixes a path typo in the search route description
(`/api/markdown/{id}` -> `/api/markdowns/{id}`).

Note: depends on elastic#270181 for the `options.oasOperationObject`
type broadening (async return + `description` + `x-codeSamples`). Typecheck
fails on this branch until that PR lands and our base branch absorbs it; the
runtime behavior already works because the OAS generator deep-merges whatever
the thunk returns.

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne @cursoragent
overlays/markdowns: point externalDocs at the Text panels page
96139ed 
The tag-level externalDocs block and the in-prose "markdown panel" link
both pointed at the generic Dashboards page. The canonical reference for
markdown content is `explore-analyze/visualize/text-panels`, which also
has a "Save and reuse Markdown panels across dashboards" section that
matches exactly what this API enables.

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne @cursoragent
markdowns: enrich content description, examples, and align with bump_…
c873b5d 
…slim

Three small follow-ups to round out the Markdowns API docs polish.

1. content field — clarify that the value is GitHub-flavored Markdown and
   list the supported elements. The previous description ("The markdown
   text content rendered by the panel.") didn't tell API users what they
   could actually put in there.

2. Example payloads — replace the placeholder one-sentence body with a
   realistic Markdown document that exercises headings, paragraphs, bold,
   inline code, bullet lists, blockquotes, and links. Refactor the
   response examples to reuse markdownCreateBody / markdownUpdateBody so
   request and response examples can't drift.

3. kibana.overlays.bump_slim.yaml — add the Markdowns API to the
   tech-preview redirect treatment used for Dashboards and
   Visualizations. The slim pipeline now strips each Markdowns operation
   down to a redirect notice pointing at the external full-spec host;
   the full reference still ships through kibana.external.yaml.

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne @cursoragent
markdowns: drop em dashes from prose we added
2c687d0 
House style avoids em dashes. Replaces the em dashes I introduced in the
last few commits with commas, colons, or rewrites, in oas_examples.ts,
embeddable/schemas.ts, and the Markdowns blocks added to
kibana.overlays.bump_slim.yaml. Leaves the pre-existing Dashboards and
Visualizations blocks alone (out of scope for this PR).

Co-authored-by: Cursor <cursoragent@cursor.com>
@florent-leborgne

florent-leborgne commented Jun 24, 2026

Copy link
Copy Markdown
Owner Author

was made for the example and to use as ref for the dev team, closing

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@florent-leborgne