Metadata-Version: 2.3
Name: jentic-openapi-tools
Version: 1.0.0a55
Summary: Workspace root for Jentic OpenAPI Tools
Author: Jentic
Author-email: Jentic <hello@jentic.com>
License: Apache-2.0
Requires-Dist: jentic-openapi-common~=1.0.0a55
Requires-Dist: jentic-openapi-datamodels~=1.0.0a55
Requires-Dist: jentic-openapi-parser~=1.0.0a55
Requires-Dist: jentic-openapi-transformer~=1.0.0a55
Requires-Dist: jentic-openapi-transformer-redocly~=1.0.0a55
Requires-Dist: jentic-openapi-traverse~=1.0.0a55
Requires-Dist: jentic-openapi-validator~=1.0.0a55
Requires-Dist: jentic-openapi-validator-redocly~=1.0.0a55
Requires-Dist: jentic-openapi-validator-spectral~=1.0.0a55
Requires-Dist: jentic-openapi-validator-speclynx~=1.0.0a55
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/jentic/jentic-openapi-tools
Description-Content-Type: text/markdown

# Jentic OpenAPI Tools

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

[![Discord](https://img.shields.io/badge/JOIN%20OUR%20DISCORD-COMMUNITY-7289DA?style=plastic&logo=discord&logoColor=white)](https://discord.gg/yrxmDZWMqB)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-3.0-40c463.svg)](https://github.com/jentic/jentic-openapi-tools/blob/HEAD/CODE_OF_CONDUCT.md)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/jentic/jentic-openapi-tools/blob/HEAD/LICENSE)
[![PyPI version](https://badge.fury.io/py/jentic-openapi-tools.svg)](https://badge.fury.io/py/jentic-openapi-tools)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

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

```bash
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:

```bash
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

```python
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

```python
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:

```bash
# 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](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-validator) for the full CLI reference.

### Transforming OpenAPI Documents

```python
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](https://github.com/jentic/jentic-openapi-tools/tree/HEAD)**                                                           | Meta-package that installs all workspace packages   |
| **[jentic-openapi-common](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-common)**                           | Common utilities and shared functionality           |
| **[jentic-openapi-datamodels](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-datamodels)**                   | OpenAPI data models and structures                  |
| **[jentic-openapi-parser](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-parser)**                           | OpenAPI document parsing with pluggable backends    |
| **[jentic-openapi-traverse](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-traverse)**                       | OpenAPI document traversal utilities                |
| **[jentic-openapi-transformer](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-transformer)**                 | OpenAPI document transformation and bundling        |
| **[jentic-openapi-transformer-redocly](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-transformer-redocly)** | Redocly-based transformation backend                |
| **[jentic-openapi-validator](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-validator)**                     | OpenAPI document validation with pluggable backends |
| **[jentic-openapi-validator-redocly](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-validator-redocly)**     | Redocly-based validation backend                    |
| **[jentic-openapi-validator-spectral](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/jentic-openapi-validator-spectral)**   | Spectral-based validation backend                   |
| **[jentic-openapi-validator-speclynx](https://github.com/jentic/jentic-openapi-tools/tree/HEAD/packages/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](https://github.com/jentic/jentic-openapi-tools/blob/HEAD/DEVELOPMENT.md)** - Setup instructions,
  testing, and development workflows
- **[Contributing Guidelines](https://github.com/jentic/jentic-openapi-tools/blob/HEAD/CONTRIBUTING.md)** - 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](https://jentic.com)
