https://github.com/vrerv/openapi-markdown
Convert openapi spec to markdown file
https://github.com/vrerv/openapi-markdown
markdown openapi
Last synced: 10 months ago
JSON representation
Convert openapi spec to markdown file
- Host: GitHub
- URL: https://github.com/vrerv/openapi-markdown
- Owner: vrerv
- License: mit
- Created: 2023-04-06T11:17:05.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-27T08:03:37.000Z (11 months ago)
- Last Synced: 2025-03-25T22:14:30.314Z (10 months ago)
- Topics: markdown, openapi
- Language: Python
- Homepage:
- Size: 60.5 KB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI Documentation Generator
This is a Python script that generates API documentation from an OpenAPI specification file.
## Usage
`pip install openapi-markdown`
### CLI
You can use `openapi2markdown` command as follows:
```
% openapi2markdown --help
Usage: openapi2markdown [OPTIONS] INPUT_FILE [OUTPUT_FILE]
Convert OpenAPI spec to Markdown documentation.
INPUT_FILE: Path to OpenAPI specification file (JSON or YAML) OUTPUT_FILE:
Path where markdown file will be generated (optional, defaults to INPUT_FILE
with .md extension)
Options:
-t, --templates-dir DIRECTORY Custom templates directory path
-f, --filter-paths TEXT Only generate apis that start with the given
path, multiple paths are allowed
```
### Library
```python
from openapi_markdown.generator import to_markdown
apiFile = "./tests/openapi.json"
outputFile = "api_doc.md"
templatesDir = "templates"
options = {
'filter_paths': ['/client']
}
to_markdown(apiFile, outputFile, templates_dir, options)
```
- If you want to use your own template, creates 'templates' directory and put [`api_doc_template.md.j2`](src/openapi_markdown/templates/api_doc_template.md.j2) file in it.
- You can change templates directory by passing it as the 3rd argument of `to_markdown`.
### Default templates
There are internal templates you can use. If not set default is used.
* templates - default
* templates/embed - prints objects hierarchially as list in every request/response
## Development
### Requirements
- Python 3.x
- json
- PyYAML
- openapi-core
- Jinja2
`pip install -r requirement.txt`
install a project in editble mode
`pip install -e ./`
run tests
`python -m unittest`
### Deploy
```
python3 -m pip install --upgrade twine
```
```
./pypi.sh
```