How to break swagger 2.0 JSON file into multiple modules
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 has a "api":{} object for breaking it down. That appears to be missing from the 2.0 schema (http://json.schemastore.org/swagger-2.0). All that defines is a single "paths" array where it bundles all the API endpoints into that single array. The effect of this in the swagger-ui is there is a single "default" category that everything gets bundled into and no way that I can tell to split it up.
TLDR: How do you split operations from paths in the swagger 2.0 schema
Answer
You actually ask several questions in one, and I'll try answering them all.
In Swagger 1.2 and prior to it, the file splitting was mandatory and artificial. It was meant as a way to group operations, and Swagger 2.0 offers and alternative method to do that (more on it soon).
Swagger 2.0 is indeed a single file, which allows for external files wherever $ref is used. You cannot split a single service into several files and combine them as one, but you can specify operations for specific paths externally (again, using the $ref property).
We're currently in the process of finalizing the ability to collate several micro-services into a single collection, but eventually, each micro-service is still going to be a single file.
As mentioned, the grouping of operations in Swagger 2.0 has changed, and the concept of a 'resource' no longer exists. Instead, there are tags (with the "tags" property) which can be assigned per operation. The tags is an array of values, and unlike previous versions, each operation can exist under multiple tags if needed. In Swagger-UI, all operations that have no tags defined will end up under the default tag, which is the behavior you've seen. There's an additional tags property at the top-level object that allows you to add descriptions to tags and set their order, but it is not mandatory to include it.
As a final note, I have no idea how the json-schema of Swagger 2.0 ended up in http://json.schemastore.org/swagger-2.0 but it is certainly not up to date. The most up-to-date schema can be found here - http://swagger.io/v2/schema.json - and it is still under development. Keep in mind that the source of truth is the spec (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) and not the schema, so in case of conflicts, the spec 'wins'.
Edit:
We just published a guide on referencing. It may help with some use cases - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md