LCORE-433: ability to generate OpenAPI documentation #383
Conversation
WalkthroughIntroduces a Makefile target to generate Markdown documentation from docs/openapi.json using openapi-to-markdown, updates README with the new target description, and adds the openapi-to-md dev dependency in pyproject.toml. Changes
Sequence Diagram(s)sequenceDiagram
actor Developer
participant Make as Make (openapi-doc)
participant O2M as openapi-to-markdown
participant Repo as docs/
Developer->>Make: make openapi-doc
Make->>O2M: Generate Markdown from docs/openapi.json
O2M-->>Repo: Write docs/output.md
Make-->>Developer: Target completed
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🔭 Outside diff range comments (1)
README.md (1)
300-302: Prevent broken link: ensure the generated filename matches or commit the doc.The link points to docs/openapi.md, but the Makefile currently outputs docs/output.md. Either:
- Adjust Makefile to generate docs/openapi.md (recommended; see Makefile comment), or
- Update this link to the actual generated file and ensure it’s committed or published via Pages.
Also ensure the file is generated and committed or published so this link works on GitHub.
Apply this diff if you prefer to update the link instead (only if you keep the current Makefile output path):
-* [OpenAPI documentation](docs/openapi.md) +* [OpenAPI documentation](docs/output.md)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (3)
Makefile(1 hunks)README.md(1 hunks)pyproject.toml(1 hunks)
🔇 Additional comments (2)
pyproject.toml (1)
79-79: Confirm CLI and pre-release usage
- The package installs the
openapi-to-markdownCLI (withapi2mdas an alias), which matches your Makefile invocation on line 41.- As of today there is no final release on PyPI—only pre-releases (0.1.0b1 and 0.1.0b2).
- Using
openapi-to-md>=0.1.0b2will pull in this pre-release now and automatically upgrade to any future stable release.- If you need strict reproducibility, pin to
==0.1.0b2until a final version is published.No code changes required unless you prefer exact version pinning.
README.md (1)
264-265: LGTM: Target listed and described consistently.
| openapi-doc: docs/openapi.json ## Generate OpenAPI documentation | ||
| openapi-to-markdown --input_file docs/openapi.json --output_file docs/output.md | ||
|
|
There was a problem hiding this comment.
Align output filename with README link (docs/openapi.md vs docs/output.md).
README links to docs/openapi.md, but the Makefile generates docs/output.md. This will produce a broken link.
Apply this diff to generate the expected file:
-openapi-doc: docs/openapi.json ## Generate OpenAPI documentation
- openapi-to-markdown --input_file docs/openapi.json --output_file docs/output.md
+openapi-doc: docs/openapi.json ## Generate OpenAPI documentation
+ openapi-to-markdown --input_file docs/openapi.json --output_file docs/openapi.md📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| openapi-doc: docs/openapi.json ## Generate OpenAPI documentation | |
| openapi-to-markdown --input_file docs/openapi.json --output_file docs/output.md | |
| openapi-doc: docs/openapi.json ## Generate OpenAPI documentation | |
| openapi-to-markdown --input_file docs/openapi.json --output_file docs/openapi.md |
🤖 Prompt for AI Agents
In Makefile around lines 40 to 42, the Make target writes the OpenAPI Markdown
to docs/output.md while README expects docs/openapi.md; change the output
filename in the openapi-doc recipe to docs/openapi.md so the generated file
matches the README link and avoids a broken link.
🛠️ Refactor suggestion
Make target resilient and run within the uv environment.
- Ensure docs/openapi.json is built automatically by depending on the schema target.
- Execute the CLI via uv to use the project’s virtual environment consistently (as done elsewhere in this Makefile).
[Suggest combined change below; verify the CLI name/flags in the next comment.]
Apply this diff:
-openapi-doc: docs/openapi.json ## Generate OpenAPI documentation
- openapi-to-markdown --input_file docs/openapi.json --output_file docs/openapi.md
+openapi-doc: schema docs/openapi.json ## Generate OpenAPI documentation
+ uv run openapi-to-markdown --input_file docs/openapi.json --output_file docs/openapi.mdCommittable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In Makefile around lines 40-42, the openapi-doc target should depend on the
target that builds docs/openapi.json and should invoke the CLI through the
project's virtual environment runner; modify the target so docs/openapi.json is
declared as a prerequisite (e.g. openapi-doc: docs/openapi.json) and replace the
direct CLI invocation with the uv-backed invocation used elsewhere (e.g. run the
openapi-to-markdown command via uv so it uses the venv), keeping the same
input/output arguments and flags.
💡 Verification agent
🧩 Analysis chain
Verify CLI name and flags match the dependency (openapi-to-md).
The dependency added is openapi-to-md, but the command uses openapi-to-markdown. The CLI entry point and flag names may differ (e.g., openapi-to-md vs openapi-to-markdown; --input/--output vs --input_file/--output_file). Please confirm the correct binary and flags.
Run this script to identify usage and reconcile names, and to flag a missing generated file:
And verify the correct CLI/flags on the web:
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching for CLI invocations..."
rg -n "openapi-to-(markdown|md)" -A2 -B2
echo
echo "Checking README link target existence..."
if [ -f docs/openapi.md ]; then
echo "OK: docs/openapi.md exists"
else
echo "WARN: docs/openapi.md is missing; Makefile should generate it or the file should be committed"
fiLength of output: 1441
🌐 Web query:
What is the correct CLI name and usage for the PyPI package "openapi-to-md"? Is the command "openapi-to-md" or "openapi-to-markdown", and what are the expected flag names for input/output?
💡 Result:
The PyPI package you’re looking for is not “openapi-to-md”; that name refers to an npm package whose CLI is openapi-to-md with Node-style flags.[1] For Python, there are similarly named packages, but their CLIs differ:
-
open-api-schemas-to-markdown (PyPI) provides the CLI oa-to-md, not openapi-to-md or openapi-to-markdown.[4]
Usage: oa-to-md INPUT_FILE OUTPUT_FILE [locale]. Flags are positional only; there are no -i/-o flags. Example: oa-to-md open_api.yml documentation.md.[4] -
openapi-markdown (PyPI) provides the CLI openapi2markdown.[7]
Usage: openapi2markdown [OPTIONS] INPUT_FILE [OUTPUT_FILE]. Optional flags include:- -t, --templates-dir DIRECTORY
- -f, --filter-paths TEXT
Output file is optional; if omitted, it defaults to INPUT_FILE with a .md extension.[7]
Therefore:
- The command “openapi-to-md” is the npm tool’s CLI, not a Python CLI.[1]
- For Python CLIs:
- Use oa-to-md (positional input/output, no -i/-o flags).[4]
- Or use openapi2markdown with the options above (no -i/-o; output is positional or inferred).[7]
Citations:
- 1: https://www.npmjs.com/package/openapi-to-md
- 2: https://openapi-generator.tech/docs/customization
- 3: https://ballerina.io/learn/openapi-tool/
- 4: https://pypi.org/project/open-api-schemas-to-markdown/
- 5: https://techdocs.studio/blog/openapi-to-markdown
- 6: https://github.com/entrepreneur-interet-general/open_api_schemas_to_markdown
- 7: https://pypi.org/project/openapi-markdown/
- 8: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_openapi_output/
- 9: https://github.com/OpenAPITools/openapi-diff
- 10: https://github.com/openapi-generators/openapi-python-client
Use the correct OpenAPI-to-Markdown CLI and flags
The Makefile currently invokes openapi-to-markdown --input_file docs/openapi.json --output_file docs/output.md, but:
- Your
pyproject.tomldepends onopenapi-to-md, which is an npm package (not a Python tool) and provides a different CLI. - No Python tool named
openapi-to-markdownis installed, so the Makefile target will fail.
You have two Python-native options—pick one and align both dependency and Makefile:
• openapi-markdown (PyPI)
– Dependency: replace "openapi-to-md>=0.1.0b2" with e.g. "openapi-markdown>=1.0.0"
– CLI: openapi2markdown
– Usage (positional):
openapi2markdown docs/openapi.json docs/output.md
• open-api-schemas-to-markdown (PyPI)
– Dependency: replace "openapi-to-md>=0.1.0b2" with e.g. "open-api-schemas-to-markdown>=0.2.0"
– CLI: oa-to-md
– Usage (positional):
oa-to-md docs/openapi.json docs/output.md
Locations to update:
- pyproject.toml: swap out
openapi-to-mdfor your chosen Python package - Makefile (lines 40–42): invoke the matching CLI and positional arguments
🤖 Prompt for AI Agents
In Makefile around lines 40–42 and pyproject.toml, the Makefile calls a
non‑existent Python CLI `openapi-to-markdown` while pyproject currently depends
on `openapi-to-md` (an npm package); replace the dependency with the Python
package `openapi-markdown>=1.0.0` in pyproject.toml and update the Makefile
target to call the matching CLI `openapi2markdown` with positional args (e.g.
`openapi2markdown docs/openapi.json docs/output.md`), ensuring the dependency
name and the Makefile command match.
1 participant
Description
LCORE-433: ability to generate OpenAPI documentation
Type of change
Related Tickets & Documents
Summary by CodeRabbit
Documentation
Chores