Support for multiple $refs inside a single object

[glen-84]

It would be really useful to be able to do something like this:

paths:
 $ref: "/operations/pets.yaml" # Multiple paths
 $ref: "/operations/stores.yaml" # Multiple paths
 $ref: "/operations/users.yaml" # Multiple paths

Where each file includes multiple paths. For example (pets.yaml):

/pets:
 post:
 # ...
/pets/findByStatus:
 get:
 # ...

This would make it easier to organize a large API.

Edit:

It could also be an array, like this:

paths:
 $ref:
 - "/operations/pets.yaml"
 - "/operations/stores.yaml"
 - "/operations/users.yaml"

[IvanGoncharov]

Swagger spec, define '$ref' as follows:
The Reference Object is a JSON Reference that uses a JSON Pointer as its value.

References used through entire spec and most importantly inside Schema object.
What mean if $ref behaviour will change it will totally ruin compatibility with JSON Schema and JSON Reference and all tooling which being build around them.

Another problem is how you would handle merge conflicts?
For example /operations/pets.yaml and /operations/stores.yaml both have same key inside.
Or one contain an object and another an array.

But I totally support your idea about allowing to split paths into separate files.
Instead of reinventing the wheel, we could use RAML approach to this problem. And make paths recursive structure, so your example will look like this:

paths:
 /pets:
 $ref: "/operations/pets.yaml" # Multiple paths
 /stores:
 $ref: "/operations/stores.yaml" # Multiple paths
 /users:
 $ref: "/operations/users.yaml" # Multiple paths

And 'pets.yaml' will looks like this:

post:
 # ...
/findByStatus:
 get:
 # ...

@glen-84 Is this proposal will solve your problem?

P.S. It could also solve path parameters duplication problem.

[glen-84]

It's quite surprising to me that the existing standards don't support this. I don't suppose this is likely to change?

As for merge conflicts, if I create two equal paths with the Swagger editor, it just uses the last one. It could be the same, or it could be a setting if you want it to throw an error.

Nested paths might be an option, although it feels a bit weird having the nested paths at the same level as post/get etc.

Could allOf be used at all?

paths:
 allOf:
 - $ref: "/operations/pets.yaml"
 - $ref: "/operations/stores.yaml"
 - /users:
 get:
 # ...

... that may be completely incorrect or make no sense – I don't know very much about JSON schema. 😄

[IvanGoncharov]

I don't suppose this is likely to change?

In any case it should be changes to JSON Pointer spec.

Could allOf be used at all?

No, 'allOf' supported only inside Schema Object.
Swagger is very strict format and you can see all supported fields here

[kulkarniankita]

+1 for adding allof to paths so multiple paths/APIs can be referenced

[wannabesrevenge]

+1 I am looking for any work around right now for allowing path urls and their subsequent path objects to be defined in multiple external files. Does anyone have any suggestions?

[glen-84]

@wannabesrevenge I'm currently using something like this:

paths:
 # Blogs
 # -- Blogs
 /blogs:
 $ref: "operations/blogs/blogs.yaml#/Blogs"
 /blogs/{id}:
 $ref: "operations/blogs/blogs.yaml#/Blog"
 # -- Blog Posts
 /blogs/{id}/posts:
 $ref: "operations/blogs/blog-posts.yaml#/BlogPosts"
 /blogs/posts/{id}:
 $ref: "operations/blogs/blog-posts.yaml#/BlogPost"
 /blogs/posts/{id}/comments:
 $ref: "operations/blogs/blog-posts.yaml#/BlogPostComments"

I don't think it's possible to move the actual paths to separate files.

[wannabesrevenge]

That's a shame. I'm hoping that "merge" in JSON schema v5 (i think it's v5) will help. I settled for doing this the same way as you. In one way it's nice because its explicit, but it is definitely not completely DRY in principle. Now if we add a route to one microservice api, we must also add the route to the master api.

[Giri-oss]

+1 for supporting recursive structure for paths

[OhDavit]

+1 need this

[danitome24]

+1

[LandonSchropp]

👍 for this appraoch:

paths:
 $ref:
 - "/operations/pets.yaml"
 - "/operations/stores.yaml"
 - "/operations/users.yaml"

It's simple and easy to understand.

@IvanGoncharov: I could think of a couple ways to resolve conflicts. Apologies if I'm missing something large here, but it seems like you could do something like this:

• If the references are both objects, the later values for the keys overwrite the earlier values for the keys. This would work the same way Object.assign() overwrites values.
• If they're both arrays, they're concatenated.
• Otherwise, the second reference overwrites the first (strings, booleans, etc.).

[erikfox]

@LandonSchropp I agree. Would pleasantly mimic familiar Object.assign() behavior here.

Merging objects with same properties

var o1 = { a: 1, b: 1, c: 1 };
var o2 = { b: 2, c: 2 };
var o3 = { c: 3 };

var obj = Object.assign({}, o1, o2, o3);
console.log(obj); // { a: 1, b: 2, c: 3 }

The properties are overwritten by other objects that have the same properties later in the parameters order.