baukit-openapi 0.10.21

Small OpenAPI metadata, serialization, writing, and drift-check helpers.
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

use baukit_openapi::{OpenApiMetadata, fill_missing_response_descriptions, serialize_schema};
use serde_json::{Value, json};
use utoipa::openapi::OpenApi;

fn document() -> OpenApi {
    serde_json::from_value(json!({
        "openapi": "3.1.0",
        "info": {"title": "test", "version": "1"},
        "paths": {
            "/items": {
                "get": {"responses": {
                    "200": {"description": "", "content": {"application/json": {"schema": {"type": "string"}}}},
                    "400": {"description": "Product validation error"},
                    "500": {"$ref": "#/components/responses/Failure"},
                    "default": {}, "4XX": {}, "599": {}
                }, "callbacks": {
                    "updated": {"{$request.body#/callback}": {"post": {"responses": {"202": {}}}}},
                    "shared": {"$ref": "#/components/callbacks/Shared"}
                }},
                "put": {"responses": {"201": {}}},
                "post": {"responses": {"202": {}}},
                "delete": {"responses": {"204": {}}},
                "options": {"responses": {"204": {}}},
                "head": {"responses": {"200": {}}},
                "patch": {"responses": {"200": {}}},
                "trace": {"responses": {"200": {}}}
            }
        },
        "webhooks": {"changed": {"post": {"responses": {"204": {}}}}},
        "components": {
            "responses": {"Failure": {}, "Alias": {"$ref": "#/components/responses/Failure"}},
            "callbacks": {"Shared": {"{$request.body#/url}": {"post": {"responses": {"200": {}}}}}},
            "pathItems": {"SharedPath": {"get": {"responses": {"404": {}}}}}
        }
    })).expect("OpenAPI fixture")
}

fn assert_response_descriptions(value: &Value) -> usize {
    match value {
        Value::Object(object) => object
            .iter()
            .map(|(key, child)| {
                let responses = if key == "responses" {
                    let responses = child.as_object().expect("response map");
                    for response in responses.values() {
                        if response.get("$ref").is_none() {
                            assert!(
                                response
                                    .get("description")
                                    .and_then(Value::as_str)
                                    .is_some_and(|description| !description.is_empty()),
                                "{response}"
                            );
                        }
                    }
                    responses.len()
                } else {
                    0
                };
                responses + assert_response_descriptions(child)
            })
            .sum(),
        Value::Array(array) => array.iter().map(assert_response_descriptions).sum(),
        _ => 0,
    }
}

#[test]
fn fills_every_response_context_and_preserves_product_content() {
    let mut document = document();
    let before = serde_json::to_value(&document).expect("serialize");
    assert!(
        before["paths"]["/items"]["get"]["responses"]["200"]
            .get("description")
            .is_none()
    );
    fill_missing_response_descriptions(&mut document);
    let after = serde_json::to_value(&document).expect("serialize");
    assert_eq!(after["openapi"], "3.1.0");
    assert_eq!(assert_response_descriptions(&after), 19);
    let responses = &after["paths"]["/items"]["get"]["responses"];
    assert_eq!(responses["200"]["description"], "OK");
    assert_eq!(
        responses["200"]["content"],
        before["paths"]["/items"]["get"]["responses"]["200"]["content"]
    );
    assert_eq!(responses["400"]["description"], "Product validation error");
    assert_eq!(
        responses["500"],
        before["paths"]["/items"]["get"]["responses"]["500"]
    );
    for status in ["default", "4XX", "599"] {
        assert_eq!(responses[status]["description"], "Response");
    }
    assert_eq!(
        after["paths"]["/items"]["delete"]["responses"]["204"]["description"],
        "No Content"
    );
    assert_eq!(
        after["components"]["pathItems"]["SharedPath"]["get"]["responses"]["404"]["description"],
        "Not Found"
    );
    fill_missing_response_descriptions(&mut document);
    assert_eq!(serde_json::to_value(&document).expect("serialize"), after);
}

#[test]
fn metadata_and_serialization_fill_descriptions_by_default() {
    let mut document = document();
    let serialized: Value =
        serde_json::from_str(&serialize_schema(&document).expect("schema")).expect("JSON");
    assert_eq!(assert_response_descriptions(&serialized), 19);
    let untouched = serde_json::to_value(&document).expect("serialize");
    assert!(
        untouched["paths"]["/items"]["get"]["responses"]["200"]
            .get("description")
            .is_none()
    );
    OpenApiMetadata::new("Test", "1", "API").apply_to(&mut document);
    assert_eq!(
        assert_response_descriptions(&serde_json::to_value(&document).expect("serialize")),
        19
    );
}