0
# OpenAPI Documentation Generation
1

2
Automatically generates documentation from OpenAPI specification files with support for both Markdown and MkDocs styles. This MkDocs plugin processes `[OAD(...)]` tags in Markdown files and replaces them with comprehensive API documentation generated from OpenAPI/Swagger specifications.
3

4
## Capabilities
5

6
### Plugin Configuration
7

8
Configure the OpenAPI documentation plugin in your MkDocs configuration file.
9

10
```python { .api }
11
class MkDocsOpenAPIDocumentationPlugin(BasePlugin):
12
    """
13
    MkDocs plugin for generating documentation from OpenAPI specification files.
14
    
15
    Configuration:
16
    - use_pymdownx (bool): Whether to use PyMdown extensions for enhanced Markdown
17
    """
18
    config_scheme = (("use_pymdownx", Type(bool, default=False)),)
19
```
20

21
### Markdown Processing
22

23
The plugin processes Markdown content during the build phase, replacing OpenAPI tags with generated documentation.
24

25
```python { .api }
26
def on_page_markdown(self, markdown, page, *args, **kwargs):
27
    """
28
    Processes Markdown content to replace [OAD(...)] tags with OpenAPI documentation.
29
    
30
    Parameters:
31
    - markdown (str): The Markdown content of the page
32
    - page (Page): The MkDocs page object
33
    
34
    Returns:
35
    str: Modified Markdown with OpenAPI documentation injected
36
    """
37
```
38

39
### Style Configuration
40

41
The plugin supports different output styles based on your MkDocs setup.
42

43
```python { .api }
44
def _get_style(self) -> str:
45
    """
46
    Returns the documentation style based on configuration.
47
    
48
    Returns:
49
    str: "MKDOCS" if use_pymdownx is True, "MARKDOWN" otherwise
50
    """
51
```
52

53
## Usage Examples
54

55
### Basic Usage
56

57
Add the plugin to your `mkdocs.yml`:
58

59
```yaml
60
plugins:
61
  - neoteroi.mkdocsoad
62
```
63

64
In your Markdown files, reference OpenAPI specifications:
65

66
```markdown
67
# API Documentation
68

69
[OAD(./openapi.yaml)]
70
```
71

72
### Advanced Configuration
73

74
Configure the plugin with PyMdown extensions:
75

76
```yaml
77
plugins:
78
  - neoteroi.mkdocsoad:
79
      use_pymdownx: true
80

81
markdown_extensions:
82
  - pymdownx.superfences
83
  - pymdownx.tabbed
84
```
85

86
### Supported Source Types
87

88
The plugin supports various OpenAPI specification sources:
89

90
```markdown
91
<!-- Local YAML file -->
92
[OAD(./specs/api.yaml)]
93

94
<!-- Local JSON file -->
95
[OAD(./specs/api.json)]
96

97
<!-- Relative path -->
98
[OAD(../shared/openapi.yaml)]
99

100
<!-- URL (if supported by underlying library) -->
101
[OAD(https://example.com/api/openapi.json)]
102
```
103

104
### Multiple API Specifications
105

106
Include multiple API specifications in a single page:
107

108
```markdown
109
# API Documentation
110

111
## User API
112
[OAD(./user-api.yaml)]
113

114
## Product API
115
[OAD(./product-api.yaml)]
116

117
## Orders API
118
[OAD(./orders-api.yaml)]
119
```
120

121
## Integration
122

123
### MkDocs Integration
124

125
The plugin integrates seamlessly with MkDocs' build process:
126

127
1. Reads OpenAPI specification files during page processing
128
2. Generates Markdown documentation using essentials-openapi library
129
3. Injects generated content into the page before final rendering
130
4. Supports MkDocs' file resolution and path handling
131

132
### Error Handling
133

134
The plugin handles various error conditions gracefully:
135

136
- Missing OpenAPI specification files are logged as warnings
137
- Invalid OpenAPI specifications are reported with detailed error messages
138
- Malformed `[OAD(...)]` tags are left unchanged and logged
139

140
### Performance Considerations
141

142
- OpenAPI specifications are processed once per build
143
- Large API specifications may increase build time
144
- Consider using local files rather than remote URLs for better performance