fix(cli): tweak required argument names and styles + validate CLI documentation drift (#45)

Author: dotkas

.github/copilot-instructions.md

@@ -11,6 +11,20 @@
 
 - Prefer Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`.
 
+## CLI usage examples
+
+- In every `oapi-codegen` command example (README, docs, `--help` text, the
+  Makefile, example folders), always put options first and the positional
+  `<SPEC_FILE>` last, matching the generated `--help` usage line
+  (e.g. `oapi-codegen --config-file cfg.yaml --output-file out.rs spec.yaml`).
+
+## CLI definition is the single source of truth
+
+- The clap CLI lives in `crates/oapi-codegen/src/cli.rs`. After changing any
+  flag, argument, help text, or the `EXAMPLES` block, run `make update-docs` to
+  regenerate `docs/cli.md` (it is generated — never edit it by hand). CI's
+  `make verify-generated` fails on drift.
+
 # Rust Coding Conventions and Best Practices
 
 Follow idiomatic Rust practices and community standards when writing Rust code.

.prettierignore

@@ -4,3 +4,6 @@ node_modules/
 
 # Lockfiles are not formatted by Prettier
 Cargo.lock
+
+# Generated from the clap CLI definition by `make update-docs`
+docs/cli.md

Cargo.lock

@@ -53,26 +53,31 @@ test-e2e: ## Run the Docker end-to-end test (generated server + client over HTTP
 update-generated: ## Refresh generated files from the coverage fixtures
 	UPDATE_GENERATED=1 cargo test -p oapi-codegen --test coverage
 
+.PHONY: update-docs
+update-docs: ## Refresh docs/cli.md from the clap CLI definition
+	UPDATE_DOCS=1 cargo test -p oapi-codegen --test cli_docs
+
 .PHONY: generate-example
 generate-example: ## Regenerate the composed bookstore example from its OpenAPI spec
 	cd examples/bookstore && \
-		cargo run -q -p oapi-codegen -- schemas/common.yaml --config oapi-codegen-common.yaml && \
-		cargo run -q -p oapi-codegen -- schemas/catalog.yaml --config oapi-codegen-catalog.yaml && \
-		cargo run -q -p oapi-codegen -- openapi.yaml --config oapi-codegen-server.yaml && \
-		cargo run -q -p oapi-codegen -- openapi.yaml --config oapi-codegen-client.yaml
+		cargo run -q -p oapi-codegen -- --config-file oapi-codegen-common.yaml schemas/common.yaml && \
+		cargo run -q -p oapi-codegen -- --config-file oapi-codegen-catalog.yaml schemas/catalog.yaml && \
+		cargo run -q -p oapi-codegen -- --config-file oapi-codegen-server.yaml openapi.yaml && \
+		cargo run -q -p oapi-codegen -- --config-file oapi-codegen-client.yaml openapi.yaml
 
 .PHONY: verify-generated
-verify-generated: ## Regenerate all generated code and fail if it drifts from what is committed
+verify-generated: ## Regenerate all generated files and fail if they drift from what is committed
 	$(MAKE) generate-example
 	$(MAKE) update-generated
-	@if [ -n "$$(git status --porcelain -- examples/bookstore/generated crates/oapi-codegen/tests/generated)" ]; then \
-		echo "ERROR: generated code is out of date."; \
-		echo "Run 'make generate-example' and 'make update-generated', then commit the result."; \
-		git status --porcelain -- examples/bookstore/generated crates/oapi-codegen/tests/generated; \
-		git --no-pager diff -- examples/bookstore/generated crates/oapi-codegen/tests/generated; \
+	$(MAKE) update-docs
+	@if [ -n "$$(git status --porcelain -- examples/bookstore/generated crates/oapi-codegen/tests/generated docs/cli.md)" ]; then \
+		echo "ERROR: generated files are out of date."; \
+		echo "Run 'make generate-example', 'make update-generated' and 'make update-docs', then commit the result."; \
+		git status --porcelain -- examples/bookstore/generated crates/oapi-codegen/tests/generated docs/cli.md; \
+		git --no-pager diff -- examples/bookstore/generated crates/oapi-codegen/tests/generated docs/cli.md; \
 		exit 1; \
 	fi
-	@echo "Generated code is up to date."
+	@echo "Generated files are up to date."
 
 .PHONY: docs
 docs: ## Generate and open Rust documentation

Makefile

@@ -7,7 +7,7 @@ Generate idiomatic Rust APIs and clients from OpenAPI 3 specifications, inspired
 
 ```sh
 cargo install oapi-codegen
-oapi-codegen --config cfg.yaml --output src/api.rs openapi.yaml
+oapi-codegen --config-file cfg.yaml --output-file src/api.rs openapi.yaml
 ```
 
 See [docs/](docs/) for installation, configuration, and extensions.
@@ -30,7 +30,7 @@ differ:
 - Blocking `reqwest` client — no async runtime forced on consumers.
 - Targets OpenAPI 3.0.
 - Reuses your `oapi-codegen` YAML config — unknown keys are ignored.
-- Explicit over implicit: `--config` and an output path are required, and
+- Explicit over implicit: `--config-file` and an output path are required, and
   empty generation fails loudly (Go defaults these and prints to stdout).
 - `x-rust-*` vendor extensions; `x-go-*` keys ignored.
 

README.md

@@ -28,13 +28,10 @@ serde_yaml = "0.9.34"
 syn = { version = "2.0.118", features = ["full"] }
 
 [dev-dependencies]
-# chrono/uuid only type-check the generated model outputs (which reference
-# them); axum type-checks the generated server output; reqwest type-checks the
-# generated client output; openapiv3 backs the coverage-matrix anchor in
-# tests/coverage.rs. None are needed by the generator itself.
 axum = { version = "0.8.9", features = ["multipart"] }
 axum-extra = { version = "0.12.6", features = ["query", "cookie"] }
 chrono = { version = "0.4.45", features = ["serde"] }
+clap-markdown = "0.1.5"
 openapiv3 = "2.2.0"
 percent-encoding = "2.3.2"
 reqwest = { version = "0.12.28", default-features = false, features = ["blocking", "json", "multipart"] }

crates/oapi-codegen/Cargo.toml

@@ -0,0 +1,44 @@
+//! The command-line interface definition.
+//!
+//! The [`Cli`] struct is the single source of truth for the CLI: the binary
+//! parses it, and the `cli_docs` integration test renders it to Markdown so
+//! `docs/cli.md` never drifts from the real interface.
+
+use std::path::PathBuf;
+
+use clap::Parser;
+
+/// Extra `--help` text with worked examples.
+pub const EXAMPLES: &str = "\
+Examples:
+  # Write generated code, selecting artifacts in the config file:
+  oapi-codegen --config-file oapi-codegen.yaml --output-file src/api.rs api.yaml
+
+  # The output path may instead come from the config's `output:` key:
+  oapi-codegen --config-file oapi-codegen.yaml api.yaml
+
+A config file is required, must enable at least one artifact, and an output
+path must be given via --output-file or the config's `output:` key:
+  # oapi-codegen.yaml
+  output: src/api.rs
+  generate:
+    models: true
+    std-http-server: true
+    client: true";
+
+/// Generate idiomatic Rust from an OpenAPI 3 specification.
+#[derive(Debug, Parser)]
+#[command(name = "oapi-codegen", version, about, after_long_help = EXAMPLES)]
+pub struct Cli {
+    /// Path to the OpenAPI 3 specification (YAML or JSON).
+    pub spec_file: PathBuf,
+
+    /// Path to an `oapi-codegen` YAML config file (required).
+    #[arg(short = 'c', long)]
+    pub config_file: PathBuf,
+
+    /// Output file path (overrides the config `output:`). Required unless the
+    /// config sets `output:`.
+    #[arg(short = 'o', long)]
+    pub output_file: Option<PathBuf>,
+}

crates/oapi-codegen/src/cli.rs

@@ -56,7 +56,7 @@ pub fn report_error(err: &Error) {
 pub fn report_no_output() {
     eprintln!("{} no output destination was given.", "error:".red().bold());
     eprintln!(
-        "  {} pass `--output <file>` on the command line, or set `output:` in your config.",
+        "  {} pass `--output-file <file>` on the command line, or set `output:` in your config.",
         "hint:".cyan().bold()
     );
 }

crates/oapi-codegen/src/console.rs

@@ -5,6 +5,7 @@
 //! generator, its operations ([`lower::paths`] → [`ir`]), then emit formatted Rust
 //! source ([`emit`]). [`Config`] mirrors `oapi-codegen`'s YAML configuration.
 
+pub mod cli;
 pub mod config;
 pub mod emit;
 pub mod error;

crates/oapi-codegen/src/lib.rs

@@ -14,45 +14,11 @@ use clap::Parser;
 use oapi_codegen::Config;
 use oapi_codegen::Error;
 use oapi_codegen::Result;
+use oapi_codegen::cli::Cli;
 use oapi_codegen::config::Generate;
 
 use crate::console::SpecStats;
 
-/// Extra `--help` text with worked examples.
-const EXAMPLES: &str = "\
-Examples:
-  # Write generated code, selecting artifacts in the config file:
-  oapi-codegen api.yaml --config oapi-codegen.yaml --output src/api.rs
-
-  # The output path may instead come from the config's `output:` key:
-  oapi-codegen api.yaml --config oapi-codegen.yaml
-
-A config file is required, must enable at least one artifact, and an output
-path must be given via --output or the config's `output:` key:
-  # oapi-codegen.yaml
-  output: src/api.rs
-  generate:
-    models: true
-    std-http-server: true
-    client: true";
-
-/// Generate idiomatic Rust from an OpenAPI 3 specification.
-#[derive(Debug, Parser)]
-#[command(name = "oapi-codegen", version, about, after_long_help = EXAMPLES)]
-struct Cli {
-    /// Path to the OpenAPI 3 specification (YAML or JSON).
-    spec: PathBuf,
-
-    /// Path to an `oapi-codegen` YAML config file (required).
-    #[arg(short, long)]
-    config: PathBuf,
-
-    /// Output file path (overrides the config `output`). Required unless the
-    /// config sets `output`.
-    #[arg(short, long)]
-    output: Option<PathBuf>,
-}
-
 /// A failure that has enough context to be reported to the user.
 enum CliFailure {
     /// A generator/loader error occurred.
@@ -116,7 +82,7 @@ fn main() -> ExitCode {
 
 /// Run the generator according to the parsed CLI arguments.
 fn run(cli: &Cli) -> std::result::Result<(), CliFailure> {
-    let config = Config::load(&cli.config)?;
+    let config = Config::load(&cli.config_file)?;
 
     if config.generate.embedded_spec {
         return Err(CliFailure::Generator(Error::Unimplemented("embedded-spec".to_owned())));
@@ -125,20 +91,20 @@ fn run(cli: &Cli) -> std::result::Result<(), CliFailure> {
     let generate = &config.generate;
     if !generate.models && !generate.std_http_server && !generate.client && !generate.server_urls {
         return Err(CliFailure::NoArtifacts {
-            config: cli.config.clone(),
+            config: cli.config_file.clone(),
         });
     }
 
-    let output = cli.output.clone().or_else(|| {
+    let output = cli.output_file.clone().or_else(|| {
         return config.output.clone();
     });
     let output = output.ok_or(CliFailure::NoOutput)?;
 
-    let code = oapi_codegen::generate(&cli.spec, &config)?;
+    let code = oapi_codegen::generate(&cli.spec_file, &config)?;
     if console::is_effectively_empty(&code) {
-        let stats = spec_stats(&cli.spec, &config)?;
+        let stats = spec_stats(&cli.spec_file, &config)?;
         return Err(CliFailure::EmptyOutput {
-            spec: cli.spec.clone(),
+            spec: cli.spec_file.clone(),
             stats,
             generate: config.generate.clone(),
         });