I\'m trying to break my API document up into multiple JSON files that can be edited independently. All the examples I\'ve been able to find use the Swagger 1.2 schema which
I've written about this in this blog post. You can basically use JSON Refs library to resolve all your little Swagger files into one large one and use it in the tools.
I wrote a Swagger/OpenAPI preprocessor to ease authoring of specifications.
https://github.com/dolmen-go/openapi-preprocessor/
In particular it supports $ref pointing to external files and allows to edit your spec as multiple files, but produce a single file for maximum compatibility with tools that will consume it.