G: G4 document every error code and both content types per response
This commit is contained in:
1 parent
34a1e1644c
commit
214e074cca
5 files changed
+82
-22
No files matched your search
+16
-4
@@ -136,7 +136,7 @@
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Log lines; `text/event-stream` when following",
|
||||
"description": "Log lines, or `text/event-stream` with `stdout`/`stderr` events when following",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
@@ -145,6 +145,11 @@
|
||||
"$ref": "#/components/schemas/LogLine"
|
||||
}
|
||||
}
|
||||
},
|
||||
"text/event-stream": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -585,9 +590,14 @@
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The peer's body, with `x-slinuxm-peer`, `Content-Type` (`application/json` or `text/event-stream`) and the peer's status",
|
||||
"description": "The peer's body with the peer's status and `x-slinuxm-peer`; JSON, or `text/event-stream` for a follow",
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"text/event-stream": {
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
@@ -1194,7 +1204,9 @@
|
||||
"bad_request",
|
||||
"unauthorized",
|
||||
"unavailable",
|
||||
"internal"
|
||||
"internal",
|
||||
"method_not_allowed",
|
||||
"forbidden_host"
|
||||
]
|
||||
},
|
||||
"message": {
|
||||
|
||||
@@ -43,3 +43,5 @@ Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets i
|
||||
Docs: `docs/api.md` gains a "Generated reference (OpenAPI)" section (what the file contains, `GET /api/v1/openapi.json`, `slinuxm openapi [--peers]`, regeneration, what the tests guard) and a route-table row; `README.md` gets a short paragraph in the REST section. `config.example.toml` needs nothing (no new key). `docs/README.md` does not list `docs/openapi.json` yet; it is outside this workstream's owned files, so the merger should add the row.
|
||||
|
||||
Verification: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test` green (10 tests in `tests/openapi.rs`, 12 unit tests in `src/openapi.rs`/`src/cli.rs`); `cargo tree -i openssl` empty; the committed spec contains no token, token-file path or URL other than the documented default server. No nix build was run; no VM test is involved in this workstream.
|
||||
|
||||
- 2026-10-20: **G4 self-review fixes.** Three accuracy gaps found on a second read: the `ErrorBody.code` enum listed only the `AppError` codes, but two status-only bodies reuse `error_response` (`method_not_allowed` from the 405 fallback, `forbidden_host` from the auth-off Host guard), so both are now documented and `every_error_code_is_documented` ties the enum to `AppError::code()` plus those two; the docker `logs` and the peer pass-through 200s now declare both `application/json` and `text/event-stream` instead of JSON only; `schema_type` no longer maps an unknown JSON Schema type name to `object` (it leaves the type out), so the converter cannot invent a type the DTO does not have. Spec regenerated.
|
||||
+3
-1
@@ -125,7 +125,9 @@ pub(crate) struct LogParams {
|
||||
description = "`1`/`true` streams new lines as SSE, `0`/`false` (default) returns a snapshot"
|
||||
)),
|
||||
responses(
|
||||
(status = 200, body = Vec<LogLine>, description = "Log lines; `text/event-stream` when following"),
|
||||
(status = 200,
|
||||
description = "Log lines, or `text/event-stream` with `stdout`/`stderr` events when following",
|
||||
content((Vec<LogLine> = "application/json"), (String = "text/event-stream"))),
|
||||
(status = 400, body = ErrorBody, description = "Invalid query parameter"),
|
||||
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
|
||||
(status = 404, body = ErrorBody, description = "Unknown container"),
|
||||
|
||||
+3
-1
@@ -112,7 +112,9 @@ pub(crate) async fn one(
|
||||
description = "Peer route below `/api/v1`, e.g. `systemd/units`"
|
||||
)),
|
||||
responses(
|
||||
(status = 200, body = String, description = "The peer's body, with `x-slinuxm-peer`, `Content-Type` (`application/json` or `text/event-stream`) and the peer's status"),
|
||||
(status = 200,
|
||||
description = "The peer's body with the peer's status and `x-slinuxm-peer`; JSON, or `text/event-stream` for a follow",
|
||||
content((String = "application/json"), (String = "text/event-stream"))),
|
||||
(status = 400, body = ErrorBody, description = "Path or query not allowed, or a chained request (`x-slinuxm-hop`)"),
|
||||
(status = 401, body = ErrorBody, description = "Missing or unknown bearer token"),
|
||||
(status = 404, body = ErrorBody, description = "Unknown peer, or the peer answered 404"),
|
||||
|
||||
+58
-16
@@ -294,6 +294,9 @@ reflected_schema!(ContainerSummary, ContainerStatus, LogLine);
|
||||
/// schemars output, so a keyword this function does not know fails a test
|
||||
/// instead of vanishing from the document.
|
||||
fn convert(value: &Value) -> RefOr<Schema> {
|
||||
// `reflected` inlines every nested schema, so a `$ref` cannot occur; a
|
||||
// keyword this function does not know is dropped, which the parity test
|
||||
// turns into a failure as soon as a DTO starts emitting one.
|
||||
let object = value.as_object().cloned().unwrap_or_default();
|
||||
let description = object.get("description").and_then(Value::as_str);
|
||||
if let Some(items) = list(&object, "oneOf") {
|
||||
@@ -368,22 +371,27 @@ fn list<'a>(object: &'a Map<String, Value>, key: &str) -> Option<&'a Vec<Value>>
|
||||
}
|
||||
|
||||
fn schema_type(value: Option<&Value>) -> SchemaType {
|
||||
match value {
|
||||
None => SchemaType::AnyValue,
|
||||
Some(Value::String(name)) => SchemaType::Type(scalar_type(name)),
|
||||
Some(Value::Array(names)) => names
|
||||
.iter()
|
||||
.filter_map(Value::as_str)
|
||||
.map(scalar_type)
|
||||
.collect::<Vec<_>>()
|
||||
.into_iter()
|
||||
.collect::<SchemaType>(),
|
||||
Some(_) => SchemaType::AnyValue,
|
||||
let names: Vec<&str> = match value {
|
||||
Some(Value::String(name)) => vec![name.as_str()],
|
||||
Some(Value::Array(names)) => names.iter().filter_map(Value::as_str).collect(),
|
||||
_ => return SchemaType::AnyValue,
|
||||
};
|
||||
match names
|
||||
.iter()
|
||||
.filter_map(|name| scalar_type(name))
|
||||
.collect::<Vec<Type>>()
|
||||
.as_slice()
|
||||
{
|
||||
[] => SchemaType::AnyValue,
|
||||
[single] => SchemaType::Type(single.clone()),
|
||||
many => SchemaType::Array(many.to_vec()),
|
||||
}
|
||||
}
|
||||
|
||||
fn scalar_type(name: &str) -> Type {
|
||||
match name {
|
||||
/// `None` for a name utoipa cannot express, which leaves the type out rather
|
||||
/// than inventing one.
|
||||
fn scalar_type(name: &str) -> Option<Type> {
|
||||
Some(match name {
|
||||
"string" => Type::String,
|
||||
"integer" => Type::Integer,
|
||||
"number" => Type::Number,
|
||||
@@ -391,8 +399,8 @@ fn scalar_type(name: &str) -> Type {
|
||||
"object" => Type::Object,
|
||||
"array" => Type::Array,
|
||||
"null" => Type::Null,
|
||||
_ => Type::Object,
|
||||
}
|
||||
_ => return None,
|
||||
})
|
||||
}
|
||||
|
||||
fn number_value(value: &Value) -> Option<utoipa::Number> {
|
||||
@@ -461,7 +469,9 @@ handwritten_schema!(
|
||||
"bad_request",
|
||||
"unauthorized",
|
||||
"unavailable",
|
||||
"internal"
|
||||
"internal",
|
||||
"method_not_allowed",
|
||||
"forbidden_host",
|
||||
]
|
||||
.into_iter()
|
||||
.map(Value::from),
|
||||
@@ -799,6 +809,38 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
/// The `code` enum is handwritten, so it is tied to the codes the server
|
||||
/// can emit: one per `AppError` variant plus the two status-only bodies.
|
||||
#[test]
|
||||
fn every_error_code_is_documented() {
|
||||
let doc = document(false);
|
||||
let schema = component::<ErrorBody>(&doc, "ErrorBody");
|
||||
let documented: Vec<&str> = schema["properties"]["error"]["properties"]["code"]["enum"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.map(|v| v.as_str().unwrap())
|
||||
.collect();
|
||||
let errors = [
|
||||
crate::error::AppError::NotFound(String::new()),
|
||||
crate::error::AppError::BadRequest(String::new()),
|
||||
crate::error::AppError::Unauthorized(String::new()),
|
||||
crate::error::AppError::Unavailable(String::new()),
|
||||
crate::error::AppError::Internal(String::new()),
|
||||
];
|
||||
for error in &errors {
|
||||
assert!(
|
||||
documented.contains(&error.code()),
|
||||
"{} is not documented",
|
||||
error.code()
|
||||
);
|
||||
}
|
||||
for code in ["method_not_allowed", "forbidden_host"] {
|
||||
assert!(documented.contains(&code), "{code} is not documented");
|
||||
}
|
||||
assert_eq!(documented.len(), errors.len() + 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn auth_state_enum_matches_serialization() {
|
||||
let doc = document(true);
|
||||
|
||||
Reference in new issue
Block a user