Skip to content

add a description field for external doc links #4772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

miguelgrinberg
Copy link
Contributor

@miguelgrinberg miguelgrinberg commented Jul 3, 2025

Fixes #4225

This change adds a fourth column to table.csv where a description for an external documentation link can be given. This description is included in schema.json, and later transferred to the externalDocs object in the generated OpenAPI files.

Note that I have not added any descriptions, the 4th column in table.csv is empty for all rows in this PR.

@miguelgrinberg miguelgrinberg force-pushed the add-ext-docs-description branch from ee6c363 to 60809fc Compare July 3, 2025 15:07
@miguelgrinberg miguelgrinberg requested a review from lcawl July 3, 2025 15:11
@lcawl
Copy link
Contributor

lcawl commented Jul 3, 2025

To test this PR, I added a description to one of the rows in the table.csv:

ccr-auto-follow,https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/ccr-auto-follow.html,Auto-follow pattern documentation

Then I generated the output and verified that it appeared in our final OpenAPI document:

  "/_ccr/auto_follow/{name}": {
      "get": {
        "summary": "Get auto-follow patterns\n",
        "externalDocs": {
          "description": "Auto-follow pattern documentation",
          "url": "https://www.elastic.co/docs/deploy-manage/tools/cross-cluster-replication/manage-auto-follow-patterns",
          "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/ccr-get-auto-follow-pattern.html"
        }
...

And confirmed that the new link text appears in a preview of these docs:

image

Copy link
Contributor

@lcawl lcawl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per #4772 (comment) the output LGTM, thanks!

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

Successfully merging this pull request may close these issues.

Add support for OpenAPI externalDocs description
2 participants