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:
post: tags: - "section1" parameters: ...
This really helped me managing larger documentation files, which otherwise tend to get quite hard to read.