Skip to content

Add support for OpenAPI externalDocs description #4225

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
lcawl opened this issue Apr 8, 2025 · 0 comments
Open

Add support for OpenAPI externalDocs description #4225

lcawl opened this issue Apr 8, 2025 · 0 comments

Comments

@lcawl
Copy link
Contributor

lcawl commented Apr 8, 2025

🚀 Feature Proposal

Add support for custom URL labels in https://github.com./elastic/elasticsearch-specification/blob/main/specification/_doc_ids/table.csv (for example, add a third column that is a text string).
Then when a specification uses one of those IDs in @ext_doc_id, use that string in the description field of the externalDocs object per https://spec.openapis.org/oas/latest.html#external-documentation-object

Currently we have no way of supplying those descriptions, so they all default to "External documentation".

Motivation

We received the following feedback about the current behaviour: "In general, could we consider a better name than “External documentation”? To me it implies leaving Elastic.co and not leaving the serverless API docs. Maybe call it “Elasticsearch Reference Documentation” or something like that."

Example

We currently provide externalDocs links for the tags via overlays, which look like this in the final OpenAPI document:

{
      "name": "connector",
      "x-displayName": "Connector",
      "externalDocs": {
        "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/es-connectors-tutorial-api.html",
        "description": "Check out the connector API tutorial"
      }
    }

You can see that the string is properly displayed by Bump.sh, for example: https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-connector

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

No branches or pull requests

1 participant