OAI / Overlay-Specification

The OAI Overlay Specification
Apache License 2.0
57 stars 15 forks source link

How to append to a potentially non-existing array? #63

Open ralfhandl opened 1 month ago

ralfhandl commented 1 month ago

The Traits Example shows how to add query parameters for paging to an operation, which in this simple form would only work if the operation does not already have parameters.

How would this be extended to a less trivial case where operations may already have parameters?

openapi: 3.1.0
info:
  title: API with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ['paged']
      responses:
        200:
          description: OK
  /items/{id}/subitems:
    get:
      x-oai-traits: ['paged']
      parameters:
        - name: id
          in: path
          required: true
      responses:
        200:
          description: OK

Would I have to specify an action for operation objects without parameters and actions for operation objects with parameters?

overlay: 1.0.0
info:
  title: Apply Traits
  version: 1.0.0
actions:
  - target: $.paths.*.get[?@.x-oai-traits.paged && !@.parameters]
    update:
      parameters:
        - name: top
          in: query
          # ...
        - name: skip
          in: query
          # ...
  - target: $.paths.*.get[?@.x-oai-traits.paged].parameters
    update:
      name: top
      in: query
      # ...
  - target: $.paths.*.get[?@.x-oai-traits.paged].parameters
    update:
      name: skip
      in: query
      # ...