Forum Discussion

orapob's avatar
orapob
New Contributor
6 years ago

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?

2 Replies

Sort By
  • RonRatovsky's avatar
    RonRatovsky
    Moderator
    6 years ago

    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.

    • orapob's avatar
      orapob
      New Contributor
      6 years ago

      The Document Structure section in OpenAPI Specification makes 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, 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?