or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-parsing.mdindex.mdoperations-and-paths.mdschema-system.mdsecurity-system.mdspecification-structure.mdtype-system-and-enums.md
tile.json

tessl/pypi-openapi3-parser

OpenAPI v3 parser that transforms specification documents into structured Python objects for programmatic access and manipulation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/openapi3-parser@1.1.x

To install, run

npx @tessl/cli install tessl/pypi-openapi3-parser@1.1.0

index.mddocs/

OpenAPI3 Parser

A comprehensive Python library for parsing OpenAPI 3.0 specification documents into structured Python objects that can be programmatically accessed and manipulated. The library transforms YAML or JSON OpenAPI specifications into typed dataclass instances, providing a pythonic interface for working with API definitions.

Package Information

  • Package Name: openapi3-parser
  • Package Type: pypi
  • Language: Python
  • Installation: pip install openapi3-parser

Core Imports

from openapi_parser import parse

Direct imports for specific components:

from openapi_parser.specification import (
    Specification, Info, Contact, License, Server, ExternalDoc, Tag,
    Schema, Integer, Number, String, Boolean, Null, Array, Object, 
    OneOf, AnyOf, Property, Discriminator, Path, Operation, Parameter,
    RequestBody, Response, Content, Header, Security, OAuthFlow
)

from openapi_parser.enumeration import (
    DataType, IntegerFormat, NumberFormat, StringFormat, OperationMethod,
    ParameterLocation, BaseLocation, ContentType, SecurityType, 
    AuthenticationScheme, OAuthFlowType, PathParameterStyle,
    QueryParameterStyle, HeaderParameterStyle, CookieParameterStyle
)

from openapi_parser.errors import ParserError

Basic Usage

from openapi_parser import parse

# Parse from file
specification = parse('swagger.yml')

# Parse from URL
specification = parse('https://api.example.com/openapi.json')

# Parse from string
spec_content = """
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users
      responses:
        '200':
          description: Success
"""
specification = parse(spec_string=spec_content)

# Work with parsed specification
print(f"API Title: {specification.info.title}")
print(f"API Version: {specification.info.version}")

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

# Access paths and operations
for path in specification.paths:
    methods = ','.join([op.method.value for op in path.operations])
    print(f"Path: {path.url}, Methods: {methods}")

Architecture

The parser transforms OpenAPI specifications into a hierarchical structure of Python dataclasses:

  • Specification: Root container for the entire API definition
  • Info/Server/Tag: Metadata and server configuration
  • Path/Operation: API endpoints and HTTP operations
  • Schema Types: Data model definitions (String, Integer, Object, Array, etc.)
  • Parameter/RequestBody/Response: Operation input/output specifications
  • Security: Authentication and authorization schemes

This structure closely mirrors the OpenAPI 3.0 specification while providing type safety and IDE support through comprehensive type hints.

Capabilities

Core Parsing

Main parsing functionality that transforms OpenAPI specification documents into structured Python objects.

def parse(
    uri: Optional[str] = None,
    spec_string: Optional[str] = None,
    strict_enum: bool = True
) -> Specification

Core Parsing

Specification Structure

The root specification object and core metadata components including API information, servers, and documentation.

@dataclass
class Specification:
    version: str
    info: Info
    servers: Optional[list[Server]] = None
    paths: Optional[list[Path]] = None
    security: Optional[list[dict]] = None
    tags: Optional[list[Tag]] = None
    external_docs: Optional[ExternalDoc] = None
    security_schemas: Optional[dict[str, Security]] = None
    schemas: Optional[dict[str, Schema]] = None

@dataclass  
class Info:
    title: str
    version: str
    description: Optional[str] = None
    terms_of_service: Optional[str] = None
    contact: Optional[Contact] = None
    license: Optional[License] = None

Specification Structure

Schema System

Comprehensive schema type system for defining data models, validation rules, and type constraints.

@dataclass
class Schema:
    type: DataType
    title: Optional[str] = None
    description: Optional[str] = None
    nullable: Optional[bool] = False
    read_only: Optional[bool] = False
    write_only: Optional[bool] = False

@dataclass
class Object(Schema):
    properties: Optional[dict[str, Property]] = None
    required: Optional[list[str]] = None
    additional_properties: Optional[Union[bool, Schema]] = None

Schema System

Operations and Paths

API endpoint definitions with HTTP operations, parameters, request bodies, and responses.

@dataclass
class Path:
    url: str
    operations: list[Operation]
    parameters: Optional[list[Parameter]] = None
    summary: Optional[str] = None
    description: Optional[str] = None

@dataclass
class Operation:
    method: OperationMethod
    responses: list[Response]
    operation_id: Optional[str] = None
    summary: Optional[str] = None
    description: Optional[str] = None
    parameters: Optional[list[Parameter]] = None
    request_body: Optional[RequestBody] = None

Operations and Paths

Type System and Enums

Enumeration types and validation constraints that define allowed values for various OpenAPI specification fields.

class DataType(Enum):
    NULL = "null"
    INTEGER = "integer"
    NUMBER = "number"
    STRING = "string"
    BOOLEAN = "boolean"
    ARRAY = "array"
    OBJECT = "object"
    ONE_OF = "oneOf"
    ANY_OF = "anyOf"

class OperationMethod(Enum):
    GET = "get"
    POST = "post"
    PUT = "put"
    DELETE = "delete"
    PATCH = "patch"
    HEAD = "head"
    OPTIONS = "options"
    TRACE = "trace"

Type System and Enums

Security System

Authentication and authorization scheme definitions including API keys, HTTP authentication, OAuth 2.0 flows, and OpenID Connect configurations.

@dataclass
class Security:
    type: SecurityType
    location: Optional[BaseLocation] = None
    description: Optional[str] = None
    name: Optional[str] = None
    scheme: Optional[AuthenticationScheme] = None
    bearer_format: Optional[str] = None
    flows: dict[OAuthFlowType, OAuthFlow] = field(default_factory=dict)
    url: Optional[str] = None

@dataclass
class OAuthFlow:
    refresh_url: Optional[str] = None
    authorization_url: Optional[str] = None
    token_url: Optional[str] = None
    scopes: dict[str, str] = field(default_factory=dict)

Security System

Error Handling

class ParserError(Exception):
    """Base exception for all parsing errors"""

The parser raises ParserError for invalid OpenAPI specifications, including missing required fields, invalid schema structures, or unsupported OpenAPI versions.