Skip to main content

OpenAPIParser

The OpenAPIParser class parses OpenAPI/Swagger specifications and extracts operation details.

Import​

from openstackai.openapi import OpenAPIParser

Constructor​

OpenAPIParser(
    spec: str | dict,           # Spec URL, path, or dict
    validate: bool = True       # Validate spec structure
)

Basic Usage​

Parse Specification​

# From URL
parser = OpenAPIParser("https://api.example.com/openapi.json")

# From file
parser = OpenAPIParser("./specs/api.yaml")

# From dict
parser = OpenAPIParser({
    "openapi": "3.0.0",
    "info": {"title": "My API", "version": "1.0"},
    "paths": {...}
})

Get Operations​

operations = parser.get_operations()

for op in operations:
    print(f"ID: {op.operation_id}")
    print(f"Method: {op.method}")
    print(f"Path: {op.path}")
    print(f"Summary: {op.summary}")
    print(f"Parameters: {op.parameters}")

Properties​

PropertyTypeDescription
titlestrAPI title
versionstrAPI version
descriptionstrAPI description
base_urlstrBase URL
serverslistServer URLs
operationslistAll operations

Methods​

get_operations()​

Get all operations:

operations = parser.get_operations()

get_operation()​

Get specific operation:

op = parser.get_operation("getUserById")
print(op.parameters)
print(op.request_body)
print(op.responses)

get_schemas()​

Get defined schemas:

schemas = parser.get_schemas()
for name, schema in schemas.items():
    print(f"Schema: {name}")
    print(f"Properties: {schema['properties']}")

get_security_schemes()​

Get security definitions:

security = parser.get_security_schemes()
# {'api_key': {'type': 'apiKey', ...}, ...}

to_tools()​

Convert to agent tools:

tools = parser.to_tools()

# With filtering
tools = parser.to_tools(
    include_operations=["getUser", "createUser"],
    exclude_tags=["admin"]
)

Operation Object​

Each operation has:

op.operation_id     # Unique identifier
op.method           # HTTP method (get, post, etc.)
op.path             # URL path
op.summary          # Short description
op.description      # Full description
op.parameters       # List of parameters
op.request_body     # Request body schema
op.responses        # Response schemas
op.tags             # Tags for categorization
op.security         # Security requirements

Parameter Details​

for param in op.parameters:
    print(f"Name: {param['name']}")
    print(f"In: {param['in']}")  # path, query, header
    print(f"Required: {param['required']}")
    print(f"Type: {param['schema']['type']}")

Request Body​

if op.request_body:
    content_type = list(op.request_body['content'].keys())[0]
    schema = op.request_body['content'][content_type]['schema']
    print(f"Body schema: {schema}")

Validation​

from openstackai.openapi import OpenAPIParser, SpecValidationError

try:
    parser = OpenAPIParser("invalid_spec.yaml", validate=True)
except SpecValidationError as e:
    print(f"Invalid spec: {e.errors}")

Supported Versions​

VersionSupport
OpenAPI 3.0✅ Full
OpenAPI 3.1✅ Full
Swagger 2.0✅ Converted

See Also​