Repository navigation
API explorer: redesign the examples rail and operation page - #4312
Merged
Merged
Conversation
…rows Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
Docs preview (local build)Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4312/ Sample changed pages: |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Requesting changes because grouped operation collapse currently permits redirecting distinct operation contracts into a single primary-operation page, which can produce incorrect API documentation.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…names without case Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…hat state Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The native title tooltip waits about a second, so the hints on the optional path segment, the "also GET" badge, the example chip counts, the schema type spans, the sidebar method glyphs and the code card buttons all felt unresponsive next to the language dots. One delegated tippy listener now serves every element with data-tippy-content, creating each tooltip on first hover, and mounts tooltips inside the code preview dialog so its top layer does not cover them. Schema type spans without a title get no attribute at all, as an empty title showed nothing natively. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The schema type partial branched four ways to leave the attribute off spans without a title. The delegate now simply does not target an empty data-tippy-content, which keeps that rule in one place and lets the partial go back to its two branches. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… pages (per review by @github-actions) The interchangeability signature now includes each operation's security requirements (schemes and scopes, order-independent). An absent security list keys as inherit, distinct from an empty list, since OpenAPI gives them different meanings. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A generated Console or curl sample is still a correct request; telling the reader where it came from added nothing they could act on. The data-generated marker stays for scripts and tests. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…collapse (per review by @github-actions) SchemaKey no longer truncates at depth 4. Inline schemas cannot be cyclic (only references recurse, and references end the descent), so the cap only bought cheapness at the cost of merging contracts that differ below it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… review by @github-actions) The interchangeability signature now carries the operation's deprecated flag and x-beta state, so a method with a different lifecycle keeps its own page and badges. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…view by @github-actions) The interchangeability signature now carries the operation's servers (URLs, order-independent), with absent servers keyed as inherited from the document. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…se (per review by @github-actions) Each response in the interchangeability signature now carries its headers by name (case-insensitive), requiredness and schema. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… collapse (per review by @github-actions) The parameter part of the interchangeability signature now carries style, explode and allowReserved, with an unset style resolved to the OpenAPI default for the parameter's location so an explicit default and an omitted one compare equal. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…wns (per review by @github-actions) The navigation builder now hands CanonicalOperationMoniker the moniker every operation in the API would claim on its own. When the collapsed group's base moniker belongs to an operation outside the group, the page keeps the primary operation's full id instead. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Operations grouped under one API are meant to be the same call, so a group that keeps separate pages points at something in the spec worth a look. AreInterchangeable now rests on Differences, which names the facets (parameters, request body, responses, security, lifecycle, servers) the operations disagree on, and the navigation builder logs them. It also warns when a shared page cannot take its base URL because another operation owns it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…by @github-actions) The preview copy button now passes a rejection handler to the clipboard write: the error is logged, as the code block copy button does, and the icon stays as it was instead of leaving an unhandled rejection. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Kibana lists each path again under /s/{space_id}: the same call made in
a space. Longest-first put that variant on the main row with the space
prefix marked optional, which read as if the prefix were part of the
path. The spaceless path now leads and the space variant lists after
it, with nothing marked optional. A /s/{x}/… route that does not prefix
another route in the set is unaffected.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
An operation with a request example but no x-codeSamples got body-less synthetic samples, so the example body had to render as a block of its own under the carousel, with a second Request label, where a spec sample would have carried it. The synthetic samples are now built around the first request example's body: Console puts it under the request line, curl sends it with -d and a Content-Type header, and the samples attach to that example as spec samples do. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The API overview and the tag landing pages listed every path of each
operation, which doubled every Kibana row with its /s/{space_id}
variant. A row now shows the main path, with its optional segments
still marked; the operation page keeps the full list.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
showModal moves focus to the dialog's first control, the copy button, and a focused control shows its tooltip, so every preview opened with "Copy code" hanging over it. Focus now starts on the dialog itself; the first Tab reaches the copy button as before. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Requesting changes because operation-collapse equivalence and collapsed-page moniker allocation still permit publishing incorrect operation pages in specific multi-operation edge cases.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
A merged page shows each path with its dominant method (POST also GET), but its samples come from one of the merged operations and could use another of the path's methods: GET /my-index-000001/_search under a POST badge, on 136 samples across 47 Elasticsearch groups. Those methods are interchangeable, so the sample now shows the dominant one. The rewrite is anchored: a Console request line is a method at the start of a line followed by its path, the same rule the highlighter uses, so JSON bodies are never touched; curl only rewrites its -X or --request flag, keyed on the sample's URL; a description's Run line follows too, so generated samples agree with it. A sample whose method the path does not list, or whose path is not one of the operation's, and every client-library sample, stay as written. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…-0943e437 # Conflicts: # src/Elastic.ApiExplorer/OpenApiGenerator.cs # src/Elastic.Documentation.Site/Assets/main.ts
… it (per review by @github-actions) The navigation builder's set of taken monikers is now mutable and gains each collapsed page's moniker as it is created, so a second group with the same base id falls back to its primary operation's id instead of rendering over the first group's page. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…se (per review by @github-actions) The servers facet of the interchangeability signature now keys each server by its URL plus its variables (name, default, allowed values, order-independent), so two operations sharing a templated URL but constraining a variable differently keep separate pages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… by @github-actions) HTTP header names are case-insensitive, so the response headers facet now keys each header by its lowercased name. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…by @github-actions) Scopes within a security scheme are now sorted before they enter the signature, so [read, write] and [write, read] compare equal. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Requesting changes: there are correctness issues that can merge non-equivalent operations and omit expected generated curl samples in some valid input shapes.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
…e (per review by @github-actions) SchemaKey now records additionalProperties: a closed object, an open one, and a map of typed values key differently, so operations that differ only there keep separate pages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… (per review by @github-actions)
The host regex behind generated curl samples now accepts http(s)://host[:port] alongside $VAR and ${VAR} hosts, so a JSON-only example keeps its curl sample whichever form the spec uses.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Approved.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Closes elastic/docs-eng-team#895
Closes elastic/docs-eng-team#877
Closes elastic/docs-eng-team#891
Closes elastic/docs-eng-team#890
Closes elastic/docs-eng-team#928
Closes elastic/docs-eng-team#880
Closes elastic/docs-eng-team#878
Closes elastic/docs-eng-team#875
Closes elastic/docs-eng-team#927
Closes elastic/docs-eng-team#888
Part of elastic/docs-eng-team#942
Part of elastic/docs-eng-team#876
Part of elastic/docs-eng-team#929
Part of elastic/docs-eng-team#887
Follow-up: elastic/docs-eng-team#983
What
/s/{space_id}variant lists after it. Overview pages show the main path only.x-codeSamplesno longer show the body in a block of its own.Notes
curlhas no entry on the Innovation Graph, so it is ranked as Shell: after Python, before Java. This is one row inCodeSample.ByNameif the order should change.api-nav-groupingfeature flag is removed: operations that sharex-namespaceandx-api-namecollapse into one page when they are interchangeable, tag groups always classify the sidebar, and Types pages are always listed. Former per-operation URLs redirect.Create service token,Delete a connector,Get connector information,Get enrollment API key by ID,Reassign agent); the build warns about each.RenderProgress, dev-server logging) is left out on purpose and will follow in a separate PR.🤖 Generated with Claude Code