Skip to content

OpenAPI.next: Allow recursive paths #647

Closed
@IvanGoncharov

Description

@IvanGoncharov

In OpenAPI 2.0 paths like /user/{userId}/ and /user/{userId}/history considered as totally separate paths with nothing in common even path parameters. Moreover, you can't define global parameters.
I propose to allow for recursive paths, it would look like that:

paths:
  '/':
    parameters:
        - in: query
          name: globalParam
          type: string
    '/user/{userId}/':
       parameters:
          - in: path
            name: userId
            type: string
       get:
           #....
       '/history':
          get:
             #...

Pros:

  • non-breaking change, you can still define old style with /user/{userId}/ and /user/{userId}/history as separate paths.
  • allow for global parameters similar to moved reusable definitions under a single element #633, but without breaking change and JSON pointer stay nice and short #/parameters/<name>.
  • remove duplication for path parameters
  • at least party address @webron concern about adding description into pathObject see added description field #632 (comment)
  • doesn't conflict with possible extensions to path template mechanism, since recursive paths just concatenate.
  • if things like consume, produce, responses will be added into pathObject, remove a lot of duplication.
  • Easy to implement validation in JSON Schema using patternProperties.

Cons:

  • force tooling to process recursion and parameter merging

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions