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.

Write details of each endpoints in a separate yaml files.

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

Write each models in separate yaml files so that we can reuse it.

Below image refers the folder structure of defenitions

Following image refers the entry file (index.yaml)

Now combine the yaml files and generate single json file

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

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

Serve the swagger doc in html format using an express server

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

Open http://localhost:3000/api/docs/ in browser then you could see the API documentations as below