Repository navigation
docs(api): make operation summaries short titles - #4671
Merged
Merged
Conversation
API references show an operation's summary as its title, also in the menu. Several summaries held explanations, references or an error list, three operations had none, and the style varied. OpenAPI 3.0.3 defines the summary as a short summary of what the operation does and the description as a verbose explanation. Explanations move to the description. The summaries of introspectAccessToken (Auth v1 and v2), introspectAccessTokenExtended, createDPoPProof and getCredentialsInWallet become a short title, with the rest as a new description. retrieveAccessToken and checkHealth add theirs to the start of their description, and the error list of getCompoundServices moves from its summary to a description. Where the description already says the same, as for requestServiceAccessToken and validateDPoPProof, or the text added nothing, as "that could be used for different use-cases" in searchVCs, the title is just shortened. getContactInformation, deleteEndpointsByType and searchOrganizations get a summary, so Scalar no longer shows their path as the title. All summaries now use the imperative without a trailing period, start with a capital, and write "Verifiable Credential" and "DID document" the same way. This also fixes "conform" in checkHealth, "holders wallet" and "Oid4VCI". The generated Go code only changes in comments.
JorisHeadease
marked this pull request as ready for review
November 3, 2026 16:31
JorisHeadease
requested review from
Dirklectisch,
gerardsn,
reinkrul,
stevenvegt and
woutslakhorst
as code owners
November 3, 2026 16:31
reinkrul
requested changes
Nov 4, 2026
Member
|
Make sure to backport to v5.4 and v6.2 afterwards |
Co-authored-by: reinkrul <reinkrul@gmail.com>
reinkrul
approved these changes
Nov 4, 2026
Applies the review titles that weren't suggestions: requestServiceAccessToken, requestUserAccessToken and retrieveAccessToken. requestUserAccessToken keeps its EXPERIMENTAL prefix, as the operation is still experimental. The generated Go comments are updated for these titles and for the suggestions applied in the previous commit.
This was referenced Nov 5, 2026
JorisHeadease
added a commit
that referenced
this pull request
Nov 5, 2026
* docs(api): make operation summaries short titles API references show an operation's summary as its title, also in the menu. Several summaries held explanations, references or an error list, three operations had none, and the style varied. OpenAPI 3.0.3 defines the summary as a short summary of what the operation does and the description as a verbose explanation. Explanations move to the description. The summaries of introspectAccessToken (Auth v1 and v2), introspectAccessTokenExtended, createDPoPProof and getCredentialsInWallet become a short title, with the rest as a new description. retrieveAccessToken and checkHealth add theirs to the start of their description, and the error list of getCompoundServices moves from its summary to a description. Where the description already says the same, as for requestServiceAccessToken and validateDPoPProof, or the text added nothing, as "that could be used for different use-cases" in searchVCs, the title is just shortened. getContactInformation, deleteEndpointsByType and searchOrganizations get a summary, so Scalar no longer shows their path as the title. All summaries now use the imperative without a trailing period, start with a capital, and write "Verifiable Credential" and "DID document" the same way. This also fixes "conform" in checkHealth, "holders wallet" and "Oid4VCI". The generated Go code only changes in comments. * Apply batched suggestions from code review * docs(api): apply remaining review titles Applies the review titles that weren't suggestions: requestServiceAccessToken, requestUserAccessToken and retrieveAccessToken. requestUserAccessToken keeps its EXPERIMENTAL prefix, as the operation is still experimental. The generated Go comments are updated for these titles and for the suggestions applied in the previous commit. --------- (cherry picked from commit fa29b60) Co-authored-by: reinkrul <reinkrul@gmail.com>
JorisHeadease
added a commit
that referenced
this pull request
Nov 5, 2026
* docs(api): make operation summaries short titles API references show an operation's summary as its title, also in the menu. Several summaries held explanations, references or an error list, three operations had none, and the style varied. OpenAPI 3.0.3 defines the summary as a short summary of what the operation does and the description as a verbose explanation. Explanations move to the description. The summaries of introspectAccessToken (Auth v1 and v2), introspectAccessTokenExtended, createDPoPProof and getCredentialsInWallet become a short title, with the rest as a new description. retrieveAccessToken and checkHealth add theirs to the start of their description, and the error list of getCompoundServices moves from its summary to a description. Where the description already says the same, as for requestServiceAccessToken and validateDPoPProof, or the text added nothing, as "that could be used for different use-cases" in searchVCs, the title is just shortened. getContactInformation, deleteEndpointsByType and searchOrganizations get a summary, so Scalar no longer shows their path as the title. All summaries now use the imperative without a trailing period, start with a capital, and write "Verifiable Credential" and "DID document" the same way. This also fixes "conform" in checkHealth, "holders wallet" and "Oid4VCI". The generated Go code only changes in comments. * Apply batched suggestions from code review * docs(api): apply remaining review titles Applies the review titles that weren't suggestions: requestServiceAccessToken, requestUserAccessToken and retrieveAccessToken. requestUserAccessToken keeps its EXPERIMENTAL prefix, as the operation is still experimental. The generated Go comments are updated for these titles and for the suggestions applied in the previous commit. --------- (cherry picked from commit fa29b60) Co-authored-by: reinkrul <reinkrul@gmail.com>
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
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.
Operation summaries are the titles in API references: Scalar shows them as the heading of each operation and in its menu. OpenAPI 3.0.3 defines
summaryas "A short summary of what the operation does" anddescriptionas "A verbose explanation of the operation behavior" (§4.7.10). Several summaries held explanations, references or an error list, three operations had none, and the style varied. This makes all 85 summaries short titles in one style.Changes
introspectAccessToken(Auth v1 and v2),introspectAccessTokenExtended,createDPoPProofandgetCredentialsInWalletget a short title, with their former text as a new description.retrieveAccessTokenandcheckHealthadd their explanation to the start of their description. The error list ofgetCompoundServicesmoves from its summary to a description.requestServiceAccessTokenandvalidateDPoPProof, or where the text added nothing, as "that could be used for different use-cases" insearchVCs.getContactInformation,deleteEndpointsByTypeandsearchOrganizations(DID Manager). Scalar showed their path instead.checkHealth, "holders wallet" and "Oid4VCI".The generated Go code only changes in comments.
Merging with #4668
The two PRs conflict in three files:
docs/_static/didman/v1.yaml(getCompoundServices),docs/_static/vdr/v2.yaml(deactivate) anddidman/api/v1/generated.go. In both specs, keep the new summary and drop the error list below it, as #4668 declares those codes as responses, then regenerate. A trial merge in both orders built and kept all new titles and the 114 examples of #4668.Verified
go build ./...,go vetfor the API packages and for./e2e-tests/browser/...with-tags e2e_tests, and the fullgo test ./...pass.