tessl/pypi-openapi3-parser

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

—

Pending

Overview

Eval results

Files

Operations and Paths

Name: tessl/pypi-openapi3-parser
Author: tessl

The operations and paths system defines API endpoints with their HTTP operations, parameters, request bodies, and responses. This includes path definitions, operation specifications, parameter handling, and content type management for complete API endpoint documentation.

Capabilities

Path Definition

Represents an API endpoint path with its operations and shared parameters.

@dataclass
class Path:
    url: str
    summary: Optional[str] = None
    description: Optional[str] = None
    operations: list[Operation] = field(default_factory=list)
    parameters: list[Parameter] = field(default_factory=list)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

url: Path template string (e.g., "/users/{id}")
summary: Brief summary of the path
description: Detailed description of the path
operations: List of HTTP operations for this path
parameters: Path-level parameters shared by all operations
extensions: Custom path extensions (x-* properties)

Operation Definition

Represents an HTTP operation (GET, POST, etc.) with its complete specification.

@dataclass
class Operation:
    method: OperationMethod
    responses: list[Response]
    summary: Optional[str] = None
    description: Optional[str] = None
    operation_id: Optional[str] = None
    external_docs: Optional[ExternalDoc] = None
    request_body: Optional[RequestBody] = None
    deprecated: Optional[bool] = field(default=False)
    parameters: list[Parameter] = field(default_factory=list)
    tags: list[str] = field(default_factory=list)
    security: list[dict[str, Any]] = field(default_factory=list)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

method: HTTP method from OperationMethod enum
responses: List of possible responses
summary: Brief operation summary
description: Detailed operation description
operation_id: Unique identifier for the operation
external_docs: Link to external documentation
request_body: Request body specification
deprecated: Whether the operation is deprecated
parameters: Operation-specific parameters
tags: Tags for grouping/categorization
security: Security requirements for this operation
extensions: Custom operation extensions

Parameter Definition

Defines input parameters for operations including query, path, header, and cookie parameters.

@dataclass
class Parameter:
    name: str
    location: ParameterLocation
    schema: Optional[Schema] = None
    content: Optional[list[Content]] = None
    required: Optional[bool] = field(default=False)
    description: Optional[str] = None
    deprecated: Optional[bool] = field(default=False)
    style: Optional[str] = None
    explode: Optional[bool] = field(default=False)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

name: Parameter name
location: Parameter location (header, query, path, cookie)
schema: Parameter schema definition
content: Alternative content-based parameter definition
required: Whether the parameter is required
description: Parameter description
deprecated: Whether the parameter is deprecated
style: Serialization style for the parameter
explode: Whether to explode array/object parameters
extensions: Custom parameter extensions

Request Body

Defines the request body content and requirements for operations.

@dataclass
class RequestBody:
    content: list[Content]
    description: Optional[str] = None
    required: Optional[bool] = field(default=False)

Properties:

content: List of supported content types and schemas
description: Request body description
required: Whether the request body is required

Response Definition

Defines operation responses including status codes, content, and headers.

@dataclass
class Response:
    is_default: bool
    description: str
    code: Optional[int] = None
    content: Optional[list[Content]] = None
    headers: list[Header] = field(default_factory=list)

Properties:

is_default: Whether this is the default response
description: Response description (required)
code: HTTP status code (None for default responses)
content: Response content types and schemas
headers: Response headers

Content Definition

Defines content types and their associated schemas for requests and responses.

@dataclass
class Content:
    type: Union[ContentType, LooseContentType]
    schema: Schema
    example: Optional[Any] = None
    examples: dict[str, Any] = field(default_factory=dict)

Properties:

type: MIME content type (application/json, text/xml, etc.)
schema: Schema definition for the content
example: Single example value
examples: Named collection of example values

Header Definition

Defines HTTP headers for responses.

@dataclass
class Header:
    name: str
    schema: Schema
    description: Optional[str] = None
    required: Optional[bool] = field(default=False)
    deprecated: Optional[bool] = field(default=False)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

name: Header name
schema: Header value schema
description: Header description
required: Whether the header is required
deprecated: Whether the header is deprecated
extensions: Custom header extensions

Usage Examples

Access all paths and operations:

from openapi_parser import parse

spec = parse('api-spec.yml')

# List all paths and their operations
for path in spec.paths:
    print(f"Path: {path.url}")
    if path.summary:
        print(f"  Summary: {path.summary}")
    
    # List operations for this path
    for operation in path.operations:
        print(f"  {operation.method.value.upper()}: {operation.summary or 'No summary'}")
        
        # Show operation ID if present
        if operation.operation_id:
            print(f"    Operation ID: {operation.operation_id}")
        
        # Show tags
        if operation.tags:
            print(f"    Tags: {', '.join(operation.tags)}")

Examine operation parameters:

# Find operations with parameters
for path in spec.paths:
    for operation in path.operations:
        all_params = path.parameters + operation.parameters
        
        if all_params:
            print(f"{operation.method.value.upper()} {path.url}")
            
            for param in all_params:
                location = param.location.value
                required = "required" if param.required else "optional"
                print(f"  {param.name} ({location}, {required})")
                
                if param.description:
                    print(f"    Description: {param.description}")

Examine request bodies and responses:

# Check operations with request bodies
for path in spec.paths:
    for operation in path.operations:
        if operation.request_body:
            print(f"{operation.method.value.upper()} {path.url}")
            print(f"  Request body required: {operation.request_body.required}")
            
            # Show supported content types
            for content in operation.request_body.content:
                print(f"    Content-Type: {content.type}")
                print(f"    Schema: {content.schema.type.value}")
        
        # Show responses
        for response in operation.responses:
            if response.code:
                print(f"  Response {response.code}: {response.description}")
            else:
                print(f"  Default response: {response.description}")
            
            # Show response content types
            if response.content:
                for content in response.content:
                    print(f"    Content-Type: {content.type}")

Working with content types:

# Find all content types used in the API
content_types = set()

for path in spec.paths:
    for operation in path.operations:
        # Request body content types
        if operation.request_body:
            for content in operation.request_body.content:
                content_types.add(str(content.type))
        
        # Response content types
        for response in operation.responses:
            if response.content:
                for content in response.content:
                    content_types.add(str(content.type))

print("Used content types:")
for ct in sorted(content_types):
    print(f"  {ct}")

Install with Tessl CLI