Jentic OpenAPI Tools

A comprehensive Python toolkit for parsing, validating, and transforming OpenAPI documents with pluggable backend architecture.

Features

• Pluggable Backend Architecture - Support for multiple parsing, validation, and transformation strategies via entry points
• Type Safety - Full type hints with comprehensive type checking throughout
• Multiple Input Formats - Accept OpenAPI documents from file URIs, JSON/YAML strings, or Python dictionaries
• Flexible Output Types - Return results as dictionaries, strings, or custom types
• Extensible Design - Easy integration of third-party backends through standard Python entry points
• Path Security - Built-in defense against path traversal attacks
• Production Ready - Comprehensive test coverage and error handling

Installation

The recommended way to install is via the meta-package, which includes all packages and backends (parser, validator, transformer, plus the Spectral, Redocly, and SpecLynx backends):

pip install jentic-openapi-tools

This also installs the jentic-openapi-tools CLI. If you only need specific functionality, you can install individual packages instead:

pip install jentic-openapi-validator                  # Core validator with default + openapi-spec backends
pip install jentic-openapi-validator-spectral          # Add Spectral backend
pip install jentic-openapi-validator-redocly           # Add Redocly backend
pip install jentic-openapi-parser                      # Parser only
pip install jentic-openapi-transformer[redocly]        # Transformer with Redocly bundler

Note that the CLI and Python API only have access to backends whose packages are installed. Installing the meta-package is the easiest way to get everything working, especially for CI pipelines and AI agents.

Prerequisites:

• Python 3.11 or higher
• Node.js >=20.19.0 and npm (required for Redocly and Spectral backends)

Quick Start

Parsing OpenAPI Documents

from jentic.apitools.openapi.parser.core import OpenAPIParser

# Create parser with default backend
parser = OpenAPIParser()

# Parse from file
doc = parser.parse("file:///path/to/openapi.yaml")
print(doc["info"]["title"])

# Parse from YAML/JSON string
yaml_doc = """
openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths: {}
"""
doc = parser.parse(yaml_doc)

Validating OpenAPI Documents

from jentic.apitools.openapi.validator.core import OpenAPIValidator

# Create validator
validator = OpenAPIValidator()

# Validate from file
result = validator.validate("file:///path/to/openapi.yaml")

if result.valid:
    print("Document is valid!")
else:
    for diagnostic in result.diagnostics:
        print(f"Error: {diagnostic.message}")

Command-Line Interface

The jentic-openapi-validator package includes the jentic-openapi-tools CLI for validating OpenAPI documents directly from the terminal:

# Validate a local file
jentic-openapi-tools validate openapi.yaml

# Use a specific backend and get JSON output
jentic-openapi-tools validate -b spectral -f json openapi.yaml

# Validate a remote URL
jentic-openapi-tools validate https://petstore3.swagger.io/api/v3/openapi.json

The CLI supports text, JSON, and GitHub Actions annotation output formats, stdin input, parallel multi-backend execution, and standard exit codes for CI integration. See the jentic-openapi-validator README for the full CLI reference.

Transforming OpenAPI Documents

from jentic.apitools.openapi.transformer.bundler.core import OpenAPIBundler

# Bundle OpenAPI document with external reference resolution
bundler = OpenAPIBundler("redocly")
result = bundler.bundle("file:///path/to/openapi.yaml", return_type=dict)
print(result["info"]["title"])

Packages

This monorepo contains the following packages:

Package	Description
jentic-openapi-tools	Meta-package that installs all workspace packages
jentic-openapi-common	Common utilities and shared functionality
jentic-openapi-datamodels	OpenAPI data models and structures
jentic-openapi-parser	OpenAPI document parsing with pluggable backends
jentic-openapi-traverse	OpenAPI document traversal utilities
jentic-openapi-transformer	OpenAPI document transformation and bundling
jentic-openapi-transformer-redocly	Redocly-based transformation backend
jentic-openapi-validator	OpenAPI document validation with pluggable backends
jentic-openapi-validator-redocly	Redocly-based validation backend
jentic-openapi-validator-spectral	Spectral-based validation backend
jentic-openapi-validator-speclynx	SpecLynx ApiDOM-based validation backend

Each package has its own detailed README with comprehensive API documentation and examples.

Documentation

• Development Guide - Setup instructions, testing, and development workflows
• Contributing Guidelines - How to contribute to the project
• Package READMEs - See individual package directories for detailed API documentation

Architecture

The Jentic OpenAPI Tools follow a modular architecture with a plugin-based backend system:

• Core Packages - Provide base functionality and abstractions
• Backend Packages - Implement specific parsing, validation, or transformation strategies
• Entry Points - Backends register themselves via Python entry points for automatic discovery

This design allows you to:

• Start with default backends and add advanced ones as needed
• Implement custom backends for specific requirements
• Use multiple backends simultaneously for comprehensive validation

---

Built and maintained by Jentic