OpenAPI.next: Allow recursive paths

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 #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 https://github.com/OAI/OpenAPI-Specification/pull/632#issuecomment-208094651
• 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

[pduchesne]

This looks to me like a very useful feature, and i’m not sure why it was closed. Is it abandoned ?

Anyway, allow me to expose a legitimate usecase that only this nesting feature would fulfill (as fas as I understand): service composition. I’d happy to know if there’s another way to implement it.

Let’s say we have two independent services, A and B, each coming with their respective service descriptions serviceA.yaml, serviceB.yaml embedded at their roots. These services can potentially be deployed as standalone applications, on arbitrary URL subpaths, e.g. http://foo.com/serviceA, with its description then sitting at http://foo.com/serviceA/serviceA.yaml and looking like

servers:
  - description: Service A
    url: .
paths:
    ...

Then there’s a need to deploy a service C, that composes A and B under two subpaths : http://foo.com/serviceC/serviceA and http://foo.com/serviceC/serviceB. It should be possible to declare this composition in http://foo.com/serviceC/serviceC.yaml, containing something like :

servers:
  - description: Composed Service C
    url: .
paths:
  /serviceA:
    $ref: 'serviceA/serviceA.yaml'
  /serviceB:
    $ref: 'serviceB/serviceB.yaml'

Can you comment on this usecase ?

[IvanGoncharov]

It’s not an argument, just thing to note. Such functionality supported in WADL, Google Discovery, I/O Docs, RAML and probably other formats. So it looks like industry-wide practice, so it worth to consider.

But I don’t say OpenAPI should automatically borrow from other formats, especially from WADL.