title: splitting swagger definition across many files
body: <p>Question: <strong>how can I split swagger definition across files? What are the possibilities in that area?</strong> The question details are described below:</p>
  
  <h2>example of what I want - in RAML</h2>
  
  <p>I do have experience in RAML and what I do is, for example:</p>
  
  <pre><code>/settings:
    description: |
      This resource defines application &amp; components configuration
    get:
      is: [ includingCustomHeaders ]
      description: |
        Fetch entire configuration
      responses:
        200:
          body:
            example: !include samples/settings.json
            schema: !include schemas/settings.json
  </code></pre>
  
  <p>The last two lines are important here - theones with <code>!include &lt;filepath&gt;</code> - in RAML I can split my entire contract into many files that just get included dynamically by the RAML parser (and RAML parser is used by all tools that base on RAML).</p>
  
  <p>My benefit from this is that:</p>
  
  <ul>
  <li>I get my contract more clear and easier to maintain, because schemas are not inline</li>
  <li>but that's really important: <strong>I can reuse the schema files within other tools to do validation, mock generation, stubs, generate tests, etc</strong>. In other words, this way I can reuse schema files within both contract (RAML, this case) and other tools (non-RAML, non-swagger, just JSONschema-based ones).</li>
  </ul>
  
  <h2>back to  Swagger</h2>
  
  <p>As far as I read, swagger supports <code>$ref</code> keyword which allows to load external files. But is that files fetched through HTTP/AJAX or can they just be local files?</p>
  
  <p>And is that supported by the whole specification or is it just some tools that support it and some that don't?</p>
  
  <p>What I found <a href="https://github.com/swagger-api/swagger-editor/issues/233" rel="noreferrer">here</a> is that the input for swagger has to be one file. And this is extremely inconvenient for big projects:</p>
  
  <ul>
  <li>because of size</li>
  <li>and because I can't reuse the schema if I want to use something non-swagger</li>
  </ul>
  
  <p>Or, in other words, can I achieve the same with swagger, that I can with RAML - in terms of splitting files?</p>