Skip to content

Some externalDocs missing from OpenAPI document #3043

Open
@lcawl

Description

@lcawl

priority: high
effort: low?

The @ext_doc_id modifier was added in #3028
While using it in #3023, it was noticeable that some occurrences were correctly shown in the schema.json (by running make generate) but missing from the OpenAPI documents (by running make transform-to-openapi).

For example, if I add the following in specification/_global/search/_types/FieldCollapse.ts:

/**
 * @ext_doc_id collapse-search-results
 */
export class FieldCollapse {
...

... The schema.json contains:

      "kind": "interface",
      "extDocId": "collapse-search-results",
      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/collapse-search-results.html",
      "name": {
        "name": "FieldCollapse",
        "namespace": "_global.search._types"
...

But there is no corresponding change to the OpenAPI document.

I did not identify the pattern of why certain occurrences were missing, but it will warrant further investigation if we implement more of those links. It might be as simple as neglecting to add support for @ext_doc_id on one of the specification data types. Alternatively, it seems to me it might reasonably be related to the sibling issue described in #2918

This issue serves as a reminder to dig deeper into this issue so we make full use of all those links we're adding.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions