How to split Swagger (OpenAPI) spec into small files ?

To manage and collaborate the API documentations of a large project, we follow the below steps

  1. Write details of each endpoints in a separate yaml files.
  2. Write each models in separate yaml files so that we can reuse it.
  3. Combine all the yaml files using `swagger-cli`
  4. Serve the swagger doc in html format using an express server

You could checkout these example github repository for details.

In the example we have 2 endpoints `/contact` and `/product`. YAML files are created with below folder structure.

Below image refers the folder structure of defenitions

# swagger-cli bundle swagger/index.yaml --outfile swagger/index.jsonyarn doc:generate

This is the script section of package.json. doc:generate will generate a sinle json file.

Create a route api/docs using express and server the doc as follows

Providing simple solutions for complex problems.