orapob
7 years agoNew Contributor
When is a single API document too big?
The convention is that one would have a single swagger.json or openapi.json (or yaml for that matter) for the REST API provided in a api-docs folder. If one has a feature rich enterprise application with hundreds of REST endpoints there's the option to use $ref to refactor that single file into smaller ones and to use tags to assist in discovery. As new application releases makes more services available, that single file is going to grow.
Are there any best practice guides, or even anecdotal observations with particular tools, on when that single document, with it's 100's of paths definied, is too big?