Split a large OpenAPI spec

Split a large OpenAPI document into linked, maintainable files.

freeworks offlinenothing uploaded
ToolOpenAPI Splitter
Input
Output
—
Put this on your own site

The frame below runs the same code as this page, in the reader's own browser. Nothing is sent to us, and nothing is sent to you.

Pick a dark background and the text and panels follow it, so the frame stays readable on a dark page.

Preview

How it works

Paths, operations, schemas, parameters, and security components are partitioned into documents; shared definitions are emitted into a common components file and relative references are rewritten. The split preserves contract content without executing references.

  • Service or tag splits keep large specs reviewable.
  • Shared components avoid duplicated schemas.

Worked example

Split by Tags
Split an OpenAPI spec into separate specs grouped by operation tags
Input
											{"openapi":"3.0.3","info":{"title":"API","version":"1.0.0"},"paths":{"/users":{"get":{"tags":["users"],"summary":"List users"}},"/posts":{"get":{"tags":["posts"],"summary":"List posts"}}}}
Output
												{
  "users": {
    "openapi": "3.0.3",
    "info": {
      "title": "API - users",
      "version": "1.0.0"
    },
    "paths": {
      "/users": {
        "get": {
          "tags": [
            "users"
          ],
          "summary": "List users"
        }
      }
    }
  },
  "posts": {
    "openapi": "3.0.3",
    "info": {
      "title": "API - posts",
      "version": "1.0.0"
    },
    "paths": {
      "/posts": {
        "get": {
          "tags": [
            "posts"
          ],
          "summary": "List posts"
        }
      }
    }
  }
}

When to use this

Developer portals, gateway repositories, and team-owned API specs split documents.

Edge cases

  • Path parameters must remain with every operation using them.
  • Circular schema references need correct relative paths.
  • Referenced security schemes must be copied to the target file.

References