Splitting Swagger API Documentation yaml files

When documenting your API with Swagger/Swagger-UI, one really cool feature to use is the $ref syntax.

As Swagger documentation files tend to get real large und hard too read, splitting the config across multiple files might be a good idea.
With $ref you could do this quite easily.

For example you could reference a single config file per path like so:

swagger: "2.0"
basePath: "my-api/v1/"
info:
  version: "0.0.1"
  title: "my API"
tags:
  - name: "section1"
    description: "Some Section"
  - name: "section2"
    description: "Some other Section"

paths:

  ##section 1

  /section1/some/path:
    $ref: 'paths/section1_some_path.yml'

  /section1/some-other-path:
    $ref: 'paths/section1_some_other_path.yml'

Then have all actions for this path defined in a dedicated file like this:

paths/section1_some_path.yml:

post:
  tags:
  - "section1"
  parameters:
    ...

This really helped me managing larger documentation files, which otherwise tend to get quite hard to read.