This release is a pre-release and may not be stable for production use.
OpenAPI to Markdown Converter
A simple, zero-dependency CLI tool to convert OpenAPI 3.x specifications (JSON or YAML) into a clean, Redoc-style Markdown file.
this project is inspired by openapi-markdown
Features
- Converts OpenAPI 3.x JSON or YAML files.
- Generates a single, self-contained Markdown file.
- Creates a human-readable output similar to ReDoc's layout.
- Includes sections for API info, servers, paths (with parameters, request bodies, and responses), and schemas.
Installation
For direct use as a CLI tool, pipx is recommended:
pipx install openapi-to-markdown
Alternatively, you can install it with pip:
pip install openapi-to-markdown
CLI Command Names
The default command is openapi-to-markdown. You can also use api2md as an alias. Both commands provide the same functionality.
api2md --help
openapi-to-markdown --help
Usage
The CLI tool uses options for all arguments. You must provide either --input_file or --curl_url to specify the OpenAPI spec source. The output path is set with --output_file (default: output.md).
api2md --input_file <path-to-openapi-spec> [--output_file <output-markdown-file>]
api2md --curl_url <openapi-spec-url> [--output_file <output-markdown-file>]
Examples
Convert a local JSON file:
api2md --input_file my-api.json
This command generates output.md in the current directory.
Convert a YAML file and specify the output path:
api2md --input_file openapi.yaml --output_file docs/reference.md
Convert a remote OpenAPI spec:
api2md --curl_url https://petstore3.swagger.io/api/v3/openapi.json --output_file petstore.md
Filtering Only Specific APIs
You can generate documentation for only specific API paths using the --filter-paths option. This option can be used multiple times to include multiple paths. Only the APIs whose paths start with the given values will be included in the output.
Example:
api2md --input_file my-api.json \
--filter-paths /agent/apps \
--filter-paths /agent/graph \
--output_file filtered.md
Or with a remote OpenAPI spec:
api2md --curl_url https://example.com/openapi.json \
--filter-paths /agent/apps \
--filter-paths /agent/graph \
--output_file filtered.md
- You can specify as many
--filter-pathsoptions as needed. - Only the endpoints whose path starts with any of the given values will be included in the generated Markdown.
Options
--input_file PATH: Path to the OpenAPI spec file (json/yaml)--curl_url URL: URL to fetch the OpenAPI spec (json/yaml)--output_file PATH: Path to the output Markdown file (default: output.md)--templates-dir PATH: Path to a custom templates directory--filter-paths PATH: Only document APIs whose path starts with the given value (can be used multiple times)
For more options, check the help:
api2md --help
Metadata
Release files for openapi-to-md 0.1.0b2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openapi_to_md-0.1.0b2.tar.gz | 5.3 kB | Without provenance | Details for openapi_to_md-0.1.0b2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openapi_to_md-0.1.0b2-py3-none-any.whl | Python 3 | none | any | Details for openapi_to_md-0.1.0b2-py3-none-any.whl |
Total release size: 13.1 kB
Release files / openapi_to_md-0.1.0b2.tar.gz
| Download URL | openapi_to_md-0.1.0b2.tar.gz |
|---|---|
| Size | 5.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
45478c80e3b462497bb9dbf5dad7ff2230ac3653904d36e8ee9c7615a8117097
|
|
BLAKE2b-256 checksum How to use checksums |
0563b5a5db0d78f3c9504b9233ac29cdd5dc1181639d6d896aa451f47daf73af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.11 Darwin/23.3.0
|
Release files / openapi_to_md-0.1.0b2-py3-none-any.whl
| Download URL | openapi_to_md-0.1.0b2-py3-none-any.whl |
|---|---|
| Size | 7.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
20a6a289c23e431c8d3db3fd1f6b68ccedb36820ef34a075322dee083b4dec56
|
|
BLAKE2b-256 checksum How to use checksums |
c3da3234d86255d44ba5ca4a886b9d7eddfe31c6042172cfc4de894ffd04b81e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.11 Darwin/23.3.0
|
Security for openapi-to-md 0.1.0b2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.