OpenChunks

A clean and efficient Python script to split OpenAPI JSON specifications into smaller, manageable chunks based on endpoint tags. Each chunk is saved as a separate JSON file in a dedicated output directory.

Features

• Tag-based splitting: Groups endpoints by their OpenAPI tags
• Dual input support: Works with both local files and remote URLs
• Clean output: Removes empty sections for cleaner JSON files
• Safe filenames: Converts tag names to filesystem names
• Network support: Handles HTTP/HTTPS URLs with timeout and error recovery
• Comprehensive error handling: Validates input and provides helpful error messages
• Modern Python: Uses type hints and modern Python features

Installation

Using uv (Recommended)

# Clone or download the project
cd openchunks

# Install with uv
uv sync

Using pip

# Install from source
pip install .

Usage

Basic Usage

# Run with local file
python main.py path/to/your/openapi-spec.json

# Run with remote URL
python main.py https://api.example.com/openapi.json

# Run with localhost URL
python main.py http://localhost:3000/swagger.json

Examples

# Local file
python main.py petstore-api.json

# Remote API documentation
python main.py https://petstore.swagger.io/v2/swagger.json

# Local development server
python main.py http://localhost:8080/api-docs

This will create a json_chunks directory with files like:

• pets.json - All endpoints tagged with "pets"
• users.json - All endpoints tagged with "users"
• store.json - All endpoints tagged with "store"
• untagged.json - Endpoints without any tags

How It Works

The script analyzes your OpenAPI specification and:

1. Reads the JSON specification file
2. Groups operations by their tags
3. Creates separate JSON files for each tag
4. Cleans empty sections from each chunk
5. Saves files with safe names in the json_chunks directory

Tag Handling

• Tagged endpoints: Grouped by their tag names
• Untagged endpoints: Placed in an untagged.json file
• Multiple tags: Operations with multiple tags appear in multiple chunks
• Safe names: Tag names are sanitized for filesystem compatibility

Output Structure

Each generated JSON file contains a complete OpenAPI specification with:

{
  "openapi": "3.0.0",
  "info": { ... },
  "servers": [ ... ],
  "paths": {
    "/api/v1/pets": {
      "get": { ... },
      "post": { ... }
    }
  },
  "components": { ... },
  "tags": [ ... ]
}

Error Handling

The script provides helpful error messages for common issues:

• File not found: Clear indication if the input file doesn't exist
• Invalid JSON: Points out JSON parsing errors
• Missing paths: Validates that the spec contains endpoint definitions
• Write errors: Reports issues when saving chunk files

Requirements

• Python 3.8 or higher
• requests library (automatically installed via pyproject.toml)

Development

Running Tests

# Using uv
uv run python -m pytest

# Or directly
python -m pytest

Code Quality

# Format code
uv run black .

# Lint code
uv run flake8 .

# Type checking
uv run mypy .

Example OpenAPI Spec

For testing, you can use this minimal example:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Test API",
    "version": "1.0.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "tags": ["pets"],
        "summary": "Get all pets",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      },
      "post": {
        "tags": ["pets"],
        "summary": "Create a pet",
        "responses": {
          "201": {
            "description": "Created"
          }
        }
      }
    },
    "/users": {
      "get": {
        "tags": ["users"],
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

If you encounter any issues or have questions:

1. Check the error messages for specific guidance
2. Ensure your OpenAPI spec is valid JSON
3. Verify that your spec contains a paths section
4. Make sure endpoint operations have proper tags defined