0
# Core Parsing
1

2
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.
3

4
## Capabilities
5

6
### Main Parse Function
7

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

10
```python { .api }
11
def parse(
12
    uri: Optional[str] = None,
13
    spec_string: Optional[str] = None,
14
    strict_enum: bool = True
15
) -> Specification
16
```
17

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

23
**Returns:**
24
- `Specification`: Parsed specification object containing the complete API definition
25

26
**Raises:**
27
- `ParserError`: If the specification is invalid, missing required fields, or cannot be parsed
28

29
**Usage Examples:**
30

31
Parse from local file:
32
```python
33
from openapi_parser import parse
34

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

38
# JSON file  
39
spec = parse('api-spec.json')
40
```
41

42
Parse from URL:
43
```python
44
# Remote specification
45
spec = parse('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml')
46
```
47

48
Parse from string:
49
```python
50
yaml_content = '''
51
openapi: 3.0.0
52
info:
53
  title: Sample API
54
  version: 1.0.0
55
paths:
56
  /health:
57
    get:
58
      summary: Health check
59
      responses:
60
        '200':
61
          description: OK
62
'''
63

64
spec = parse(spec_string=yaml_content)
65
```
66

67
Parse with loose enum validation:
68
```python
69
# Allow custom content types and formats not in OpenAPI standard
70
spec = parse('spec.yml', strict_enum=False)
71
```
72

73
### Validation and Error Handling
74

75
The parser performs comprehensive validation of OpenAPI specifications:
76

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

82
**Common Error Scenarios:**
83

84
```python
85
from openapi_parser import parse, ParserError
86

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

94
**Parser Error Types:**
95
- Missing `openapi` version field
96
- Invalid OpenAPI version (must be 3.0.x)
97
- Malformed YAML/JSON content
98
- Invalid schema references
99
- Missing required specification components
100

101
### Supported Input Formats
102

103
The parser automatically detects and handles multiple input formats:
104

105
- **YAML**: `.yml`, `.yaml` files with YAML content
106
- **JSON**: `.json` files with JSON content  
107
- **String Content**: YAML or JSON content passed as strings
108
- **Remote Files**: HTTP/HTTPS URLs pointing to specification files
109

110
### Performance Considerations
111

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