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 ...
Forum Discussion
Actually, there isn't really such a convention. You can use a single file or multiple ones to manage your API definition. You should also consider what you consider to be a single API? While possible, it's not necessarily common to have hundreds of operations in a single API.
Within our toolset, SwaggerHub gives you the option to split your definition into multiple files, and manage common assets across multiple API definitions.
The Document Structure section in OpenAPI Specification makes a recommendation:
It is RECOMMENDED that the root OpenAPI document be named:
openapi.jsonoropenapi.yaml.Although there's no global convention that everyone follows, and OpenAPI does not have an auto-discovery aspect yet, it appears that depending on vendor, hosted services do have som convention. For example, for an IBM Liberty server, go to https://host:https_port/ibm/api/docs. For some web apps, the API document can be found in /api-docs/, or /apis/ irrespective of where they are deployed. So even if one has no control over the context root, or even the domain name, the services can be discovered.The tagging capability in swagger v2 and openapi v3 does allow one to have all of the service paths documented in a single file and still be useable. I'm not trying to reignite the auto discovery topic, but rather get input about when makes sense to split the single, convenient API document, into multiple ones.
What limits, if any, have people encountered with tools for example?
