Specification Structure

The specification structure represents the root OpenAPI document and its core metadata components. This includes the main Specification container, API information, server configurations, and documentation references that define the overall API context.

Capabilities

Root Specification

The top-level container that holds the complete parsed OpenAPI specification with all its components.

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

Properties:

• version: OpenAPI specification version (e.g., "3.0.0")
• info: API metadata and information
• servers: List of server configurations where the API is hosted
• paths: API endpoints and their operations
• security: Global security requirements
• tags: Metadata for grouping operations
• external_docs: Reference to external documentation
• security_schemas: Reusable security scheme definitions
• schemas: Reusable schema components
• extensions: Custom extensions (x-* properties)

API Information

Metadata about the API including title, version, description, and contact information.

@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
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

• title: API title/name (required)
• version: API version string (required)
• description: Detailed API description with CommonMark syntax support
• terms_of_service: URL to terms of service
• contact: Contact information for the API
• license: License information for the API
• extensions: Custom info extensions

Contact Information

Contact details for the API maintainers or support team.

@dataclass
class Contact:
    name: Optional[str] = None
    url: Optional[str] = None
    email: Optional[str] = None

Properties:

• name: Contact name/organization
• url: Contact website or support URL
• email: Contact email address

License Information

Licensing information for the API.

@dataclass
class License:
    name: str
    url: Optional[str] = None
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

• name: License name (required)
• url: URL to the license text
• extensions: Custom license extensions

Server Configuration

Server information specifying where the API is accessible.

@dataclass
class Server:
    url: str
    description: Optional[str] = None
    variables: Optional[dict] = field(default_factory=dict)
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

• url: Server URL template (required). May contain variables in {brackets}
• description: Human-readable server description
• variables: Variable definitions for URL template substitution
• extensions: Custom server extensions

External Documentation

Reference to external documentation resources.

@dataclass
class ExternalDoc:
    url: str
    description: Optional[str] = None
    extensions: Optional[dict] = field(default_factory=dict)

Properties:

• url: URL to external documentation (required)
• description: Description of the external documentation
• extensions: Custom external docs extensions

Tags

Metadata for grouping and organizing API operations.

@dataclass
class Tag:
    name: str
    description: Optional[str] = None
    external_docs: Optional[ExternalDoc] = None

Properties:

• name: Tag name (required)
• description: Tag description
• external_docs: Additional external documentation for this tag

Usage Examples

Access API metadata:

from openapi_parser import parse

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

# Basic API information
print(f"API: {spec.info.title} v{spec.info.version}")
print(f"Description: {spec.info.description}")

# Contact information
if spec.info.contact:
    contact = spec.info.contact
    print(f"Contact: {contact.name} ({contact.email})")

# License information  
if spec.info.license:
    print(f"License: {spec.info.license.name}")

Access server configurations:

# List all servers
for server in spec.servers:
    print(f"Server: {server.url}")
    if server.description:
        print(f"  Description: {server.description}")
    
    # Server variables
    for var_name, var_def in (server.variables or {}).items():
        print(f"  Variable {var_name}: {var_def}")

Work with tags:

# List all tags
for tag in spec.tags:
    print(f"Tag: {tag.name}")
    if tag.description:
        print(f"  Description: {tag.description}")