Swaggerizer

A lightweight CLI tool to modularize, maintain, and publish OpenAPI docs.

Swaggerizer takes a practical approach to OpenAPI docs management, in the sweet spot between too monolithic or too granular. It breaks up OpenAPI spec files by functional groups and uses a simple make-based system to reassemble them.

The Swaggerizer project structure makes it easy for a single writer to build and maintain OpenAPI docs, or for a team of writers to collaborate using a docs-as-code approach.

Swaggerizing your OpenAPI docs is risk free. It creates a separate source folder with the modularized project files, so you can test it out before committing to anything. Give it a try!

Features

• Create a modular OpenAPI project from a single OpenAPI YAML file:
  • Modularize an existing OpenAPI file, or start a new project from the default Petstore file
  • Use make to test and reassemble a single OpenAPI file out of the project/source files
  • Project files are set up in the openapi_src sub-directory, with the following structure:

    openapi_src/
    ├── 0_intro/        # Basic info, metadata, and tags
    ├── 1_endpoints/    # Endpoint descriptions grouped by tag (one file per tag)
    ├── 2_components/   # Reusable objects (schemas, parameters, examples, etc.)
    ├── 3_misc/         # Additional top-level sections not categorized above
    └── makefile        # Custom makefile to generate the final OpenAPI file
    

• Other features:
  • Convert OpenAPI files from JSON → YAML or YAML → JSON
  • Validate YAML/JSON file formats
  • Export an OpenAPI YAML file as HTML for publishing

Prerequisites

• Python 3.8 or later
• make

Installation

Install using pip:

pip install swaggerizer

Verify the installation:

swgrzr --help

Quick start

Create a new swaggerizer project from your existing openapi.yaml file:

swgrzr create -i openapi.yaml

Create a new swaggerizer project from the default Petstore file:

swgrzr create 

Build a testing version of the complete OpenAPI file from source:

cd openapi_src
make

Copy the current testing version of the OpenAPI file into the parent directory for publishing:

make final-build

Export the OpenAPI YAML file as HTML:

swgrzr export -i openapi.yaml

CLI usage

Syntax

swgrzr OPERATION [options]

Available operations

Common options

How it works

To create a modularized OpenAPI docs project, swaggerizer:

1. Loads the source OpenAPI YAML.
2. Detects the OpenAPI version (v2 or v3).
3. Extracts and groups the OpenAPI sections.
4. Generates the modular project source directory.
5. Adds the makefile to rebuild the spec.

Source code overview

swaggerizer/          # Metadata and packaging
├── swaggerizer/      # Python app source 
│   ├── cli.py        # CLI entry point
│   ├── files/        # Default assets
│   └── helpers/      # Helper modules

How to help

Feedback is appreciated!

Please:

• Report bugs or unexpected behavior.
• Propose enhancements to CLI commands or options.

To contribute:

1. Fork the swaggerizer repo.
2. Create a branch for your changes.
3. Run tests before submitting.
4. Open a pull request describing your changes and motivation.

Smaller, focused pull requests are preferred.