oapi-codegen 1.0.1

Generate client and server boilerplate from OpenAPI 3 specifications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
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` must 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",
        );
    }
}