oapi_codegen/
cli.rs

1//! Definition of the command-line interface.
2//!
3//! [`Cli`] is the source of truth for the CLI.
4//! The binary parses this definition.
5//! The `cli_docs` test renders this definition as Markdown.
6//! This keeps `docs/cli.md` in sync with the interface.
7
8use std::path::PathBuf;
9
10use clap::Parser;
11
12/// Extra `--help` text with examples.
13pub const EXAMPLES: &str = "\
14Examples:
15  # Write generated code. Select artifacts in the configuration file:
16  oapi-codegen --config-file oapi-codegen.yaml --output-file src/api.rs api.yaml
17
18  # You can also set output with the `output:` configuration key:
19  oapi-codegen --config-file oapi-codegen.yaml api.yaml
20
21You must provide a configuration file.
22The configuration file must enable at least one artifact.
23You must set output with --output-file or the `output:` configuration key:
24  # oapi-codegen.yaml
25  output: src/api.rs
26  generate:
27    models: true
28    std-http-server: true
29    client: true";
30
31/// Generate Rust code from an OpenAPI 3 specification.
32#[derive(Debug, Parser)]
33#[command(name = "oapi-codegen", version, about, after_long_help = EXAMPLES)]
34pub struct Cli {
35    /// Path to the OpenAPI 3 specification (YAML or JSON).
36    pub spec_file: PathBuf,
37
38    /// Path to an `oapi-codegen` YAML configuration file (required).
39    #[arg(short = 'c', long)]
40    pub config_file: PathBuf,
41
42    /// Output file path (overrides configuration `output:`).
43    /// Required unless the configuration sets `output:`.
44    #[arg(short = 'o', long)]
45    pub output_file: Option<PathBuf>,
46
47    /// Compare the generated code with the output file, and write nothing.
48    ///
49    /// The exit code is 0 when the output file holds the generated code.
50    /// The exit code is 1 when the file differs, or when the file is absent.
51    /// Use this in continuous integration to make stale output a failed build.
52    /// This flag reports no dependencies, because it adds none.
53    #[arg(long, conflicts_with = "install_deps")]
54    pub check: bool,
55
56    /// Fail the run when it reports a warning, and write nothing.
57    ///
58    /// The exit code is 1 when the configuration or the spec produces a warning.
59    /// Use this in continuous integration to make a new warning a failed build.
60    /// This flag rejects `--install-deps`, because a failed `cargo add` is reported
61    /// as a warning after the write, and nothing could be unwritten then.
62    #[arg(long, conflicts_with = "install_deps")]
63    pub deny_warnings: bool,
64
65    /// After the write, run `cargo add` for each required crate.
66    ///
67    /// If set, this runs with no prompt.
68    /// If stdin is interactive and the flag is not set, the CLI asks first.
69    /// If stdin is not interactive and the flag is not set, the CLI prints only the list.
70    /// `cargo add` targets the package whose `Cargo.toml` is nearest output.
71    /// It merges with an existing declaration.
72    /// A crate that already exists is updated in place.
73    #[arg(long)]
74    pub install_deps: bool,
75}
oapi_codegen/cli.rs

oapi_codegen/
cli.rs
