Metadata-Version: 2.4
Name: ziipinParser
Version: 2.0.0
Summary: OpenAPI v3 parser
Keywords: swagger,python,swagger-parser,ziipinParser,parser,openapi3,swagger-api
Author: Artem Manchenkov
Author-email: Artem Manchenkov <artem@manchenkoff.me>
License-Expression: MIT
License-File: license.txt
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: pydantic>=2.0
Requires-Dist: referencing>=0.35
Requires-Dist: pyyaml>=6.0
Requires-Python: >=3.10
Project-URL: homepage, https://pypi.org/project/ziipinParser/
Project-URL: upstream, https://github.com/manchenkoff/openapi3-parser
Description-Content-Type: text/markdown

# ziipinParser

[![PyPI - Version](https://img.shields.io/pypi/v/ziipinparser)](https://pypi.org/project/ziipinParser/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/ziipinparser)](https://clickpy.clickhouse.com/dashboard/ziipinparser)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ziipinparser)](https://pypi.org/project/ziipinParser/)
[![PyPI - Format](https://img.shields.io/pypi/format/ziipinparser)](https://pypi.org/project/ziipinParser/)

A fork of [openapi3-parser](https://github.com/manchenkoff/openapi3-parser),
published under a separate distribution name. Original attribution is retained
in `license.txt`.

Parse OpenAPI and Swagger documents into fully typed Pydantic models.
Navigate your API specification programmatically — servers, paths,
operations, parameters, schemas, security schemes, and more.

| Version | Status         |
| ------- | -------------- |
| 2.0     | Supported*     |
| 3.0     | Supported      |
| 3.1     | Supported      |
| 3.2     | Supported      |

\* Swagger 2.0 documents are normalized to OpenAPI 3.0.

## Installation

```bash
pip install ziipinParser
```

The Python import name is `ziipinParser`, matching the distribution name.

## Publishing

Build the distributions for the version in `pyproject.toml`:

```bash
uv build --out-dir dist/ziipinparser
```

Configure your PyPI API token locally using `UV_PUBLISH_TOKEN`, or configure
PyPI Trusted Publishing for your own GitHub repository. Then upload the new
distribution artifacts:

```bash
uv publish dist/ziipinparser/*
```

Use the `dist/ziipinparser/` directory when publishing. Artifacts built under
previous distribution names still contain those names in their metadata and
must not be included in the upload.

Before building a later release, update the version and empty the output
directory so it contains only the artifacts you intend to publish.

## Quick Start

```python
from ziipinParser import parse

specification = parse("swagger.yml")
print(specification.info.title)  # e.g. "User example service"
```

## Use Cases

### Parse from different sources

```python
# From file path
spec = parse("specs/openapi.yml")

# From URL
spec = parse("https://example.com/openapi.json")

# From raw string
spec = parse(spec_string="""
openapi: "3.0.0"
info:
  title: My API
  version: "1.0.0"
paths: {}
""")

# From raw string with external $refs (resolved relative to base_uri)
spec = parse(
    spec_string=open("specs/openapi.yml").read(),
    base_uri="file:///abs/path/specs/openapi.yml",
)
```

### Navigate servers, paths, and operations

```python
specification = parse("swagger.yml")

# List all servers
for server in specification.servers:
    print(f"{server.description} - {server.url}")

# Iterate paths and their HTTP methods
for path, path_item in specification.paths.items():
    methods = ", ".join(
        method for method in ("get", "put", "post", "delete", "patch")
        if getattr(path_item, method) is not None
    )
    print(f"{path}: [{methods}]")

# Inspect operation details
for path_item in specification.paths.values():
    get_op = path_item.get
    if get_op is None:
        continue
    print(f"[GET] {path}: {get_op.summary}")
    if get_op.deprecated:
        print("  (deprecated)")
    if get_op.operation_id:
        print(f"  operationId: {get_op.operation_id}")
```

### Follow `$ref` references

`$ref` entries are resolved in place and annotated with a `ref_name`
pointing back to their canonical location:

```python
schema = specification.components.schemas["Pet"]
print(schema.ref_name)  # "#/components/schemas/Pet"
```

In OpenAPI 3.1+, siblings of `$ref` (such as `default`) are preserved.
References with local siblings produce separate models so they do not change
the shared component or other references to it.

### Inspect schema defaults

JSON `null` is represented by Python `None`. Use `has_default` to distinguish
an explicit `default: null` from an omitted default:

```python
if schema.has_default:
    print(schema.default)  # May be None for an explicit default: null
else:
    print("No default declared")
```

### Error Handling

```python
from ziipinParser.errors import ParserError

try:
    spec = parse("invalid.yml")
except ParserError as e:
    print(f"Parsing failed: {e}")
    for detail in e.errors():
        print(detail["loc"], detail["msg"])
```

## Data Model

Parsed documents return a `Specification` object composed of fully typed
Pydantic models:

| Model            | Description |
| ---------------- | ----------- |
| `Specification`  | Root document — openapi, info, servers, paths, components, security |
| `Info`           | API metadata — title, version, description, contact, license |
| `Server`         | Server definition — url, description, variables |
| `PathItem`       | URL path — get/post/put/delete/patch, parameters, servers |
| `Operation`      | HTTP method — responses, parameters, request body, security |
| `Parameter`      | Path/query/header/cookie param — schema, style, required |
| `Response`       | Status code, description, content, headers |
| `RequestBody`    | Content, description, required |
| `MediaType`      | Media type — schema, example, encoding |
| `Schema`         | Data definition — type, properties, items, composition |
| `Components`     | Reusable schemas, responses, parameters, examples, headers, ... |
| `SecurityScheme` | Security scheme — apiKey, http, oauth2, openIdConnect, mutualTLS |
| `OAuthFlow`      | OAuth flow — authorization, token, scopes |
| `Header`         | Response header — name, schema, description |
| `Link`           | Link definition — operation, parameters, request body |
| `Example`        | Example — value, summary, externalValue |
| `Tag`            | Tag with optional external docs |
| `ExternalDoc`    | External documentation reference |
| `Discriminator`  | Polymorphism discriminator — property name, mapping |

See the [models](src/ziipinParser/models/) package for all available
fields and types.

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Lint
uv run ruff check src/ tests/
uv run mypy src/ tests/
uv run ty check

# Test
uv run pytest

# Format
uv run ruff format src/ tests/
```
