essentials-openapi icon indicating copy to clipboard operation
essentials-openapi copied to clipboard

Support for fragments of external docs

Open mbklein opened this issue 1 year ago • 0 comments

This is valid in OpenAPI v3:

paths:
  /collections:
    get:
      operationId: getCollections
      tags:
        - Collection
      parameters:
        - $ref: "./types.yaml#/components/parameters/as"
        - $ref: "./types.yaml#/components/parameters/page"
        - $ref: "./types.yaml#/components/parameters/size"
        - $ref: "./types.yaml#/components/parameters/sort"
      responses:
        200:
          $ref: "./types.yaml#/components/responses/SearchResponse"

But it looks like the ref handler is set up to handle two cases:

  • $ref: "path/to/file.yaml" (where the external ref is the entire external file)
  • $ref: "#/internal/ref" (where the ref is internal to the current file)

It needs a third case:

  • $ref: "path/to/file.yaml#/ref/within/external/file" (where it loads and processes the external file, and then returns the subset indicated by the fragment)

mbklein avatar Sep 03 '24 17:09 mbklein