Skip to content

LCORE-433: ability to generate OpenAPI documentation #383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 12, 2025
Merged

LCORE-433: ability to generate OpenAPI documentation #383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c840a0
LCORE-433: ability to generate OpenAPI documentation
tisnik Aug 12, 2025
79051c7
Added dev dependency
tisnik Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ format: ## Format the code into unified format
schema: ## Generate OpenAPI schema file
uv run scripts/generate_openapi_schema.py docs/openapi.json

openapi-doc: docs/openapi.json ## Generate OpenAPI documentation
openapi-to-markdown --input_file docs/openapi.json --output_file docs/output.md

Comment on lines +40 to +42
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

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.

Suggested change
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.md

Committable 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"
fi

Length 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:

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.toml depends on openapi-to-md, which is an npm package (not a Python tool) and provides a different CLI.
  • No Python tool named openapi-to-markdown is 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-md for 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.

# TODO uv migration
requirements.txt: pyproject.toml pdm.lock ## Generate requirements.txt file containing hashes for all non-devel packages
pdm export --prod --format requirements --output requirements.txt --no-extras --without evaluation
Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,7 @@ check-types Checks type hints in sources
security-check Check the project for security issues
format Format the code into unified format
schema Generate OpenAPI schema file
openapi-doc Generate OpenAPI documentation
requirements.txt Generate requirements.txt file containing hashes for all non-devel packages
shellcheck Run shellcheck
verify Run all linters
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ dev = [
"types-cachetools>=6.1.0.20250717",
"build>=1.2.2.post1",
"twine>=6.1.0",
"openapi-to-md>=0.1.0b2",
]
llslibdev = [
"fastapi>=0.115.12",
Expand Down
16 changes: 16 additions & 0 deletions uv.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.