feat: output filtering (#25)

Author: dotkas

crates/oapi-codegen/src/config.rs

@@ -56,6 +56,25 @@ pub struct OutputOptions {
     /// Keep schemas that are not referenced (no pruning).
     #[serde(default)]
     pub skip_prune: bool,
+    /// Only generate operations tagged with one of these tags (empty = all).
+    #[serde(default)]
+    pub include_tags: Vec<String>,
+    /// Skip operations tagged with any of these tags.
+    #[serde(default)]
+    pub exclude_tags: Vec<String>,
+    /// Only generate operations whose `operationId` is one of these
+    /// (empty = all).
+    #[serde(default)]
+    pub include_operation_ids: Vec<String>,
+    /// Skip operations whose `operationId` is one of these.
+    #[serde(default)]
+    pub exclude_operation_ids: Vec<String>,
+    /// Remove these component schemas from the spec before lowering, so their
+    /// models are not generated. Filtering runs before pruning; if an excluded
+    /// schema is still referenced by a retained operation or schema, generation
+    /// may fail or emit a reference to a type that is not declared.
+    #[serde(default)]
+    pub exclude_schemas: Vec<String>,
 }
 
 impl Config {

crates/oapi-codegen/src/filter.rs

@@ -0,0 +1,158 @@
+//! Spec-level operation and schema filtering.
+//!
+//! Mirrors `oapi-codegen`'s `output-options` filters: operations are dropped
+//! when they fail any active include/exclude **tag** or **operation-id** filter,
+//! and component schemas named in `exclude-schemas` are removed before lowering.
+//! Filtering runs before pruning, so removing an operation lets the prune pass
+//! drop any component schemas it uniquely referenced.
+
+use openapiv3::OpenAPI;
+use openapiv3::Operation;
+use openapiv3::PathItem;
+use openapiv3::ReferenceOr;
+
+use crate::config::OutputOptions;
+
+/// Apply the configured operation and schema filters to `doc` in place.
+pub fn apply(doc: &mut OpenAPI, opts: &OutputOptions) {
+    filter_operations(doc, opts);
+    exclude_schemas(doc, &opts.exclude_schemas);
+}
+
+/// Whether any operation-level (tag or operation-id) filter is configured.
+fn has_operation_filters(opts: &OutputOptions) -> bool {
+    return !opts.include_tags.is_empty()
+        || !opts.exclude_tags.is_empty()
+        || !opts.include_operation_ids.is_empty()
+        || !opts.exclude_operation_ids.is_empty();
+}
+
+/// Remove operations that fail any active tag or operation-id filter.
+fn filter_operations(doc: &mut OpenAPI, opts: &OutputOptions) {
+    if !has_operation_filters(opts) {
+        return;
+    }
+    for (_, entry) in doc.paths.paths.iter_mut() {
+        let ReferenceOr::Item(item) = entry else {
+            continue;
+        };
+        for slot in operation_slots(item) {
+            let remove = slot.as_ref().is_some_and(|op| {
+                return is_filtered_out(op, opts);
+            });
+            if remove {
+                *slot = None;
+            }
+        }
+    }
+}
+
+/// Mutable references to every operation slot on a path item, in a stable
+/// verb order (`get`, `put`, `post`, `delete`, `options`, `head`, `patch`,
+/// `trace`).
+fn operation_slots(item: &mut PathItem) -> [&mut Option<Operation>; 8] {
+    return [
+        &mut item.get,
+        &mut item.put,
+        &mut item.post,
+        &mut item.delete,
+        &mut item.options,
+        &mut item.head,
+        &mut item.patch,
+        &mut item.trace,
+    ];
+}
+
+/// Whether `operation` should be dropped given the configured filters.
+///
+/// An operation is kept only when it carries none of the excluded tags, carries
+/// one of the included tags (when `include-tags` is set), is not an excluded
+/// operation-id, and is an included operation-id (when `include-operation-ids`
+/// is set) — matching `oapi-codegen`'s sequential exclude-then-include filters.
+fn is_filtered_out(operation: &Operation, opts: &OutputOptions) -> bool {
+    if !opts.exclude_tags.is_empty()
+        && operation.tags.iter().any(|tag| {
+            return opts.exclude_tags.contains(tag);
+        })
+    {
+        return true;
+    }
+    if !opts.include_tags.is_empty()
+        && !operation.tags.iter().any(|tag| {
+            return opts.include_tags.contains(tag);
+        })
+    {
+        return true;
+    }
+    let id = operation.operation_id.as_deref();
+    if !opts.exclude_operation_ids.is_empty()
+        && id.is_some_and(|id| return contains_str(&opts.exclude_operation_ids, id))
+    {
+        return true;
+    }
+    if !opts.include_operation_ids.is_empty()
+        && !id.is_some_and(|id| return contains_str(&opts.include_operation_ids, id))
+    {
+        return true;
+    }
+    return false;
+}
+
+/// Whether `values` contains `needle`.
+fn contains_str(values: &[String], needle: &str) -> bool {
+    return values.iter().any(|value| {
+        return value == needle;
+    });
+}
+
+/// Drop component schemas whose names appear in `exclude`.
+fn exclude_schemas(doc: &mut OpenAPI, exclude: &[String]) {
+    if exclude.is_empty() {
+        return;
+    }
+    if let Some(components) = doc.components.as_mut() {
+        components.schemas.retain(|name, _| {
+            return !exclude.contains(name);
+        });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// `operation_slots` must reference every operation verb openapiv3
+    /// recognises: nulling all slots must leave the path item with no
+    /// operations. This cross-checks our hand-listed slots against openapiv3's
+    /// authoritative `PathItem::iter`, catching drift if a verb is ever added.
+    #[test]
+    fn operation_slots_cover_every_verb() {
+        let populated = || {
+            return Some(Operation::default());
+        };
+        let mut item = PathItem {
+            get: populated(),
+            put: populated(),
+            post: populated(),
+            delete: populated(),
+            options: populated(),
+            head: populated(),
+            patch: populated(),
+            trace: populated(),
+            ..Default::default()
+        };
+        assert_eq!(
+            item.iter().count(),
+            operation_slots(&mut item).len(),
+            "every populated verb should map to one slot"
+        );
+        for slot in operation_slots(&mut item) {
+            *slot = None;
+        }
+        assert_eq!(
+            item.iter().count(),
+            0,
+            "operation_slots must cover every verb reported by openapiv3's PathItem::iter",
+        );
+    }
+}

crates/oapi-codegen/src/lib.rs

@@ -8,6 +8,7 @@
 pub mod config;
 pub mod emit;
 pub mod error;
+pub mod filter;
 pub mod ir;
 pub mod loader;
 pub mod lower;
@@ -28,7 +29,8 @@ use crate::loader::Spec;
 /// server interface is appended when `generate.std-http-server` is set; the
 /// blocking `reqwest` client is appended when `generate.client` is set.
 pub fn generate(spec_path: &Path, config: &Config) -> Result<String> {
-    let spec = Spec::load(spec_path)?;
+    let mut spec = Spec::load(spec_path)?;
+    spec.apply_filters(&config.output_options);
     let want_server = config.generate.std_http_server;
     let want_client = config.generate.client;
     let mut module = if config.generate.models || want_server || want_client {

crates/oapi-codegen/src/loader.rs

@@ -109,6 +109,12 @@ impl Spec {
         return &self.source;
     }
 
+    /// Apply the configured operation and schema filters, mutating the spec in
+    /// place before lowering (see [`crate::filter`]).
+    pub fn apply_filters(&mut self, opts: &crate::config::OutputOptions) {
+        crate::filter::apply(&mut self.inner, opts);
+    }
+
     /// The component schemas declared in the document, in document order.
     pub fn schemas(&self) -> &IndexMap<String, ReferenceOr<Schema>> {
         let empty = EMPTY_SCHEMAS.get_or_init(IndexMap::new);

crates/oapi-codegen/tests/coverage.rs

@@ -380,6 +380,7 @@ const SERVER_FIXTURES: &[&str] = &[
     "server_multi_content_request",
     "server_multi_content_response",
     "server_prune",
+    "server_filtering",
 ];
 
 /// Server fixtures whose generation must fail with a documented error, covering
@@ -615,6 +616,7 @@ server_generated_tests!(
     server_multi_content_request,
     server_multi_content_response,
     server_prune,
+    server_filtering,
 );
 
 /// The server `#[test]`s must cover exactly the supported server fixtures.
@@ -668,6 +670,130 @@ fn skip_prune_retains_unused_schemas() {
     );
 }
 
+/// Path to the shared filtering fixture (three tagged/untagged operations).
+fn filtering_fixture() -> PathBuf {
+    return tests_dir().join("fixtures").join("server_filtering.yaml");
+}
+
+/// `exclude-tags` drops operations carrying an excluded tag, and pruning then
+/// removes any component schema the dropped operation uniquely referenced.
+#[test]
+fn filter_exclude_tags_drops_tagged_operations() {
+    let mut config = server_config();
+    config.output_options.exclude_tags = vec!["admin".to_owned()];
+
+    let generated =
+        oapi_codegen::generate(&filtering_fixture(), &config).expect("generating filtered server output failed");
+    assert!(
+        generated.contains("fn list_pets") && generated.contains("fn health_check"),
+        "operations without the excluded tag must be kept",
+    );
+    assert!(
+        !generated.contains("fn get_stats"),
+        "operations carrying an excluded tag must be dropped",
+    );
+    assert!(
+        generated.contains("struct Pet") && !generated.contains("struct Stats"),
+        "a schema referenced only by a dropped operation must be pruned",
+    );
+}
+
+/// `include-tags` keeps only operations carrying one of the included tags;
+/// untagged operations are dropped.
+#[test]
+fn filter_include_tags_keeps_only_tagged_operations() {
+    let mut config = server_config();
+    config.output_options.include_tags = vec!["pets".to_owned()];
+
+    let generated =
+        oapi_codegen::generate(&filtering_fixture(), &config).expect("generating filtered server output failed");
+    assert!(
+        generated.contains("fn list_pets"),
+        "operations with an included tag must be kept",
+    );
+    assert!(
+        !generated.contains("fn get_stats") && !generated.contains("fn health_check"),
+        "operations without an included tag (including untagged) must be dropped",
+    );
+}
+
+/// `exclude-operation-ids` drops operations by `operationId`; the rest survive.
+#[test]
+fn filter_exclude_operation_ids_drops_named_operations() {
+    let mut config = server_config();
+    config.output_options.exclude_operation_ids = vec!["healthCheck".to_owned()];
+
+    let generated =
+        oapi_codegen::generate(&filtering_fixture(), &config).expect("generating filtered server output failed");
+    assert!(
+        generated.contains("fn list_pets") && generated.contains("fn get_stats"),
+        "operations not named in exclude-operation-ids must be kept",
+    );
+    assert!(
+        !generated.contains("fn health_check"),
+        "operations named in exclude-operation-ids must be dropped",
+    );
+}
+
+/// `include-operation-ids` keeps only operations whose `operationId` is listed.
+#[test]
+fn filter_include_operation_ids_keeps_only_named_operations() {
+    let mut config = server_config();
+    config.output_options.include_operation_ids = vec!["listPets".to_owned()];
+
+    let generated =
+        oapi_codegen::generate(&filtering_fixture(), &config).expect("generating filtered server output failed");
+    assert!(
+        generated.contains("fn list_pets"),
+        "operations named in include-operation-ids must be kept",
+    );
+    assert!(
+        !generated.contains("fn get_stats") && !generated.contains("fn health_check"),
+        "operations not named in include-operation-ids must be dropped",
+    );
+}
+
+/// `exclude-schemas` removes named component schemas from models generation,
+/// leaving the rest intact. Models-only generation never prunes, so a negative
+/// control (generation without the option) proves the removal is attributable to
+/// `exclude-schemas` and not to pruning.
+#[test]
+fn filter_exclude_schemas_removes_named_models() {
+    let models_only = oapi_codegen::config::Generate {
+        models: true,
+        ..Default::default()
+    };
+
+    let baseline = oapi_codegen::Config {
+        generate: models_only.clone(),
+        ..Default::default()
+    };
+    let unfiltered =
+        oapi_codegen::generate(&filtering_fixture(), &baseline).expect("generating baseline models failed");
+    assert!(
+        unfiltered.contains("struct Standalone"),
+        "without exclude-schemas the schema must be generated (models-only never prunes)",
+    );
+
+    let config = oapi_codegen::Config {
+        generate: models_only,
+        output_options: oapi_codegen::config::OutputOptions {
+            exclude_schemas: vec!["Standalone".to_owned()],
+            ..Default::default()
+        },
+        ..Default::default()
+    };
+    let generated = oapi_codegen::generate(&filtering_fixture(), &config).expect("generating filtered models failed");
+    assert!(
+        generated.contains("struct Pet") && generated.contains("struct Stats"),
+        "schemas not named in exclude-schemas must be generated",
+    );
+    assert!(
+        !generated.contains("struct Standalone"),
+        "schemas named in exclude-schemas must not be generated",
+    );
+}
+
 /// Configuration that enables the blocking `reqwest` client generator.
 fn client_config() -> oapi_codegen::Config {
     return oapi_codegen::Config {