swaggerizer 0.1.1
CLI tool to modularize and maintain OpenAPI docs
License: Apache-2.0
Requires Python: >=3.8
Keywords: openapi, swagger, swaggerizer, cli, docs, modularize

# 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:

```bash
pip install swaggerizer
```

Verify the installation:

```bash
swgrzr --help
```

## Quick start

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

```bash
swgrzr create -i openapi.yaml
```

Create a new swaggerizer project from the default Petstore file:

```bash
swgrzr create 
```

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

```bash
cd openapi_src
make
```

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

```bash
make final-build
```

Export the OpenAPI YAML file as HTML:

```bash
swgrzr export -i openapi.yaml
```

## CLI usage

### Syntax

```
swgrzr OPERATION [options]
```

### Available operations

| Operation   | Description |
|-------------|-------------|
| create      | Create a new modularized project from an OpenAPI YAML file. |
| export      | Export the input OpenAPI YAML as a rendered HTML document. |
| json2yaml   | Convert an OpenAPI JSON file to YAML. |
| yaml2json   | Convert an OpenAPI YAML file to JSON. |
| validate    | Validate basic JSON or YAML structure. |

### Common options

| Option            | Description |
|------------------|-------------|
| -i, --input      | Input file path. Defaults vary by operation. |
| -o, --output     | Output file path. Defaults vary by operation. |
| -t, --type       | Input type for validation (`json`, `yaml`). |

## 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.