Core Parsing

The core parsing functionality transforms OpenAPI 3.0 specification documents from various sources into structured Python objects. The parser handles both local files and remote URLs, supports YAML and JSON formats, and provides flexible validation options.

Capabilities

Main Parse Function

Parses OpenAPI specification documents from files, URLs, or strings into a structured Specification object.

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

Parameters:

• uri (str, optional): Path or URL to OpenAPI specification file. Supports local file paths and HTTP/HTTPS URLs
• spec_string (str, optional): OpenAPI specification content as a string in YAML or JSON format
• strict_enum (bool): Whether to validate content types and string formats against predefined enums. When False, allows custom values beyond OpenAPI standard enums

Returns:

• Specification: Parsed specification object containing the complete API definition

Raises:

• ParserError: If the specification is invalid, missing required fields, or cannot be parsed

Usage Examples:

Parse from local file:

from openapi_parser import parse

# YAML file
spec = parse('api-spec.yml')

# JSON file  
spec = parse('api-spec.json')

Parse from URL:

# Remote specification
spec = parse('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml')

Parse from string:

yaml_content = '''
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /health:
    get:
      summary: Health check
      responses:
        '200':
          description: OK
'''

spec = parse(spec_string=yaml_content)

Parse with loose enum validation:

# Allow custom content types and formats not in OpenAPI standard
spec = parse('spec.yml', strict_enum=False)

Validation and Error Handling

The parser performs comprehensive validation of OpenAPI specifications:

• Schema Validation: Ensures required fields are present and properly structured
• Reference Resolution: Resolves $ref references within the specification
• Type Validation: Validates data types and formats according to OpenAPI 3.0 specification
• Enum Validation: When strict_enum=True, validates enumerated values against OpenAPI standards

Common Error Scenarios:

from openapi_parser import parse, ParserError

try:
    spec = parse('invalid-spec.yml')
except ParserError as e:
    print(f"Parsing failed: {e}")
    # Handle parsing errors - invalid schema, missing required fields, etc.

Parser Error Types:

• Missing openapi version field
• Invalid OpenAPI version (must be 3.0.x)
• Malformed YAML/JSON content
• Invalid schema references
• Missing required specification components

Supported Input Formats

The parser automatically detects and handles multiple input formats:

• YAML: .yml, .yaml files with YAML content
• JSON: .json files with JSON content
• String Content: YAML or JSON content passed as strings
• Remote Files: HTTP/HTTPS URLs pointing to specification files

Performance Considerations

• Caching: The parser includes internal caching for resolved references
• Memory Usage: Large specifications with complex schemas may require significant memory
• Network Requests: Remote URL parsing involves network overhead for fetching content
• Validation Overhead: strict_enum=True adds validation overhead but ensures compliance