Contributions
Re: When is a single API document too big?
The Document Structure section in OpenAPI Specificationmakes a recommendation: It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.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, hostedservices 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?3.4KViews0likes0CommentsWhen 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 tagsto assist in discovery. As new application releases makes more services available, that single file is going to grow. Arethere 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?3.5KViews0likes2Comments