copy action clarification, unsupported use case for dynamic node creation

[jeremyfiel]

re: #150

It seems the copy action only allows copying from known target locations. If more than one nodes exist, there is no way to discriminate which node shall be updated. They are all modified. I believe that's expected behavior.

The copy function fails to support one of the original use cases of copying existing content to a new, dynamic target node.
This can be seen here #121 (comment)

Outlining another use case:

The requirements:

• find all GET operations
• create a duplicate of each node with a new suffix '/meta'
• copy the entire contents of the original node
• modify the schema node value to point to a new schema for '/meta' responses
• add new parameters to '/meta' endpoints

Input

openapi: 3.2.0
info:
  title: no meta apis defined
  version: v1
paths:
  /things:
    get:
      responses:
        '200': 
          $ref: '#/components/responses/things_response'
components:
    responses:
      things_response:
        description: OK
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/things'
    schemas:
      things: {}

Couple things to consider for this copy functionality:

• the target returns results of the node values but, the spec recommends implementations return the nodelist of result paths(normalized paths) along with the node values. This is implementation defined behavior.
• there's no way to copy a node value to a new, dynamic node
• there is also no way to reuse the existing target results to extract the location(s) from the nodelist to create new nodes. The ability to extract the location would be a really nice upgrade
• there's no way to define which of the nodes from a nodelist are to be copied
• string interpolation is a touchy subject but, no mechanism exists to modify a string of an existing node value

overlay: 1.1.0
info:
  title: add meta apis
  version: v1
actions:
- target: $.paths[?@.get]
  description: find any api with a get operation and create new endpoint(s) with a /meta suffix
  update:
      ${target}.location + '/meta'
- target: $.paths[?match(@, '/meta')]
  description: copy the contents of the original get operation to the new meta api.
  copy : $.paths[?@.get]
- target: $.paths[?match(@, 'meta')].get.responses['200']
  description: fix up the schema reference for meta endpoints
  update:
    $ref: '#/components/responses/${target}_meta'
- target: $.components.parameters
  description: add $filter to components
  update:
    query_filter:
      name: $filter
      description: OData v4 $filter query parameter
      in: query
      required: false
      schema:
        type: string
- target: $.paths[?match(@, 'meta')].get.parameters
  description: add Odata $filter to all /meta endpoints
  update:
    - $ref: '#/components/parameters/query_filter'

Expected output

openapi: 3.2.0
info:
  title: New meta apis defined
  version: v1
paths:
  /things:
    get:
      responses:
        '200': 
          $ref: '#/components/responses/things_response'
 /things/meta:
    get:
     parameters:
      - $ref: '#/components/parameters/query_filter'
      responses:
        '200': 
          $ref: '#/components/responses/things_response_meta'
components:
    responses:
      things_response:
        description: OK
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/things'
      things_response_meta:
        description: OK
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/things_meta'

    schemas:
      things: {}
      things_meta: {}
    parameters:
      query_filter:
        name: $filter
        description: OData v4 $filter query parameter
        in: query
        required: false
        schema:
          type: string