OpenAPI: per-status response config + RFC 7807 problem+json support (#162)

* added status code config for open api

* Add produces_problem() / produces_problem_example() for OpenAPI (RFC 7807)

  Adds two new methods on OpenApiRouteConfig, gated under the
  problem-details feature, that document problem+json responses in the
  generated OpenAPI spec:

    cfg.produces_problem(400)
    cfg.produces_problem_example(422, Problem::new(422).with_detail("..."))

  Both use application/problem+json as the content type (RFC 7807).
  produces_problem() derives a canonical example (type, title, status)
  from the HTTP status code's reason phrase.

  The feature is forwarded from volga's problem-details flag to
  volga-open-api via the optional dep syntax, so it activates
  automatically when both openapi and problem-details are enabled.

* updated CHANGELOG

Author: RomanEmreis

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## Unreleased
+
+### Added
+* Per-status-code OpenAPI response config: `produces_*` methods now accept a status code, `IntoStatusCode` trait (supports `u16`, `u32`, `i32`, `http::StatusCode`) (#162)
+* OpenAPI `produces_problem()` and `produces_problem_example()` for `application/problem+json` responses, gated on `problem-details` feature (#162)
+
 ## 0.8.4
 
 ### Added

examples/open_api/src/main.rs

@@ -37,7 +37,9 @@ async fn main() -> std::io::Result<()> {
         api.map_get("/{name}", async |name: String| ok!(fmt: "Hello {name}"));
         api.map_get("/{name}/{age:integer}", async |Path((_name, _age)): Path<(String, u32)>| {});
         api.map_get("/named/{name}/{age}", async |path: NamedPath<Payload>| ok!(path.into_inner()))
-            .open_api(|cfg| cfg.produces_json::<Payload>());
+            .open_api(|cfg| cfg
+                .produces_json::<Payload>(200)
+                .produces_no_schema(400));
     });
 
     app.group("/file", |api| {
@@ -60,12 +62,12 @@ async fn main() -> std::io::Result<()> {
     app.map_put("/form", async |payload: Form<Payload>| payload)
         .open_api(|cfg| cfg
             .with_doc("v2")
-            .produces_form::<Payload>());
-    
+            .produces_form::<Payload>(200u16));
+
     app.map_post("/json", async |payload: Json<Payload>| payload)
         .open_api(|cfg| cfg
             .with_doc("v2")
-            .produces_json_example(Payload { name: "John".into(), age: 30 }));
+            .produces_json_example(200u16, Payload { name: "John".into(), age: 30 }));
 
     app.run().await
 }

volga-dev-cert/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "volga-dev-cert"
-version = "0.8.4"
+version = "0.8.5"
 readme = "README.md"
 description = "A Rust library for generating self-signed TLS certificates for local development."
 edition.workspace = true
@@ -17,7 +17,7 @@ keywords = ["volga", "server", "https", "tls"]
 rcgen = "0.14.7"
 
 [dev-dependencies]
-serial_test = "3.3.1"
+serial_test = "3.4.0"
 
 [lints]
 workspace = true

volga-di/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "volga-di"
-version = "0.8.4"
+version = "0.8.5"
 readme = "README.md"
 description = "Dependency Injection tools for Volga Web Framework"
 edition.workspace = true

volga-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "volga-macros"
-version = "0.8.4"
+version = "0.8.5"
 readme = "README.md"
 description = "Macros for Volga Web Framework"
 edition.workspace = true

volga-open-api/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "volga-open-api"
-version = "0.8.4"
+version = "0.8.5"
 readme = "README.md"
 description = "Volga Open API Integration"
 edition.workspace = true
@@ -21,5 +21,8 @@ serde_json = "1.0.149"
 serde_urlencoded = "0.7.1"
 serde = { version = "1.0.228", features = ["derive"] }
 
+[features]
+problem-details = []
+
 [lints]
 workspace = true

volga-open-api/src/doc.rs

@@ -69,6 +69,7 @@ mod tests {
     fn prune_unreferenced_components_keeps_only_reachable_transitive_refs() {
         let mut op = OpenApiOperation::default();
         op.set_response_body(
+            200,
             OpenApiSchema::reference("User"),
             None,
             "application/json",

volga-open-api/src/lib.rs

@@ -18,7 +18,7 @@ mod ui;
 
 pub use {
     config::{OpenApiConfig, OpenApiSpec},
-    route::OpenApiRouteConfig,
+    route::{OpenApiRouteConfig, IntoStatusCode},
     registry::OpenApiRegistry,
     doc::OpenApiDocument,
     ui::ui_html,

volga-open-api/src/op.rs

@@ -98,24 +98,38 @@ impl OpenApiOperation {
 
     pub(super) fn set_response_body(
         &mut self,
+        status: u16,
         schema: OpenApiSchema,
         example: Option<Value>,
         content_type: &str,
     ) {
+        let description = http::StatusCode::from_u16(status)
+            .ok()
+            .and_then(|s| s.canonical_reason())
+            .unwrap_or("Response")
+            .to_string();
         let response = self
             .responses
-            .entry("200".to_string())
-            .or_insert_with(|| OpenApiResponse {
-                description: "OK".to_string(),
-                content: None,
-            });
+            .entry(status.to_string())
+            .or_insert_with(|| OpenApiResponse { description, content: None });
         response.content = Some(media_content(content_type, schema, example));
     }
 
-    pub(super) fn clear_response_body(&mut self) {
-        if let Some(resp) = self.responses.get_mut("200") {
-            resp.content = None;
-        }
+    pub(super) fn clear_response_body(&mut self, status: u16) {
+        let description = http::StatusCode::from_u16(status)
+            .ok()
+            .and_then(|s| s.canonical_reason())
+            .unwrap_or("Response")
+            .to_string();
+        let response = self
+            .responses
+            .entry(status.to_string())
+            .or_insert_with(|| OpenApiResponse { description, content: None });
+        response.content = None;
+    }
+
+    pub(super) fn clear_all_responses(&mut self) {
+        self.responses.clear();
     }
 
     pub(super) fn collect_component_refs(&self, out: &mut BTreeSet<String>) {
@@ -184,6 +198,7 @@ mod tests {
             "text/plain",
         );
         operation.set_response_body(
+            200,
             OpenApiSchema::integer(),
             Some(json!(42)),
             "application/custom",
@@ -209,6 +224,42 @@ mod tests {
         );
     }
 
+    #[test]
+    fn set_response_body_non_200_status() {
+        let mut operation = OpenApiOperation::default();
+        operation.clear_all_responses();
+        operation.set_response_body(
+            201,
+            OpenApiSchema::object(),
+            None,
+            "application/json",
+        );
+
+        let json = serde_json::to_value(operation).expect("serialize");
+        assert!(json["responses"].get("200").is_none());
+        assert!(json["responses"]["201"]["content"].get("application/json").is_some());
+        assert_eq!(json["responses"]["201"]["description"], "Created");
+    }
+
+    #[test]
+    fn clear_response_body_removes_content_for_status() {
+        let mut operation = OpenApiOperation::default();
+        operation.set_response_body(200, OpenApiSchema::string(), None, "text/plain");
+        operation.clear_response_body(200);
+
+        let json = serde_json::to_value(operation).expect("serialize");
+        assert!(json["responses"]["200"].get("content").is_none());
+    }
+
+    #[test]
+    fn clear_all_responses_empties_map() {
+        let mut operation = OpenApiOperation::default();
+        operation.clear_all_responses();
+
+        let json = serde_json::to_value(operation).expect("serialize");
+        assert!(json["responses"].as_object().expect("responses object").is_empty());
+    }
+
     #[test]
     fn collect_component_refs_includes_params_request_and_response() {
         let mut operation = OpenApiOperation {
@@ -217,7 +268,7 @@ mod tests {
                 location: "path".to_string(),
                 required: true,
                 schema: OpenApiSchema::reference("PathParam"),
-            }]), 
+            }]),
             ..Default::default()
         };
 
@@ -227,6 +278,7 @@ mod tests {
             "application/json",
         );
         operation.set_response_body(
+            200,
             OpenApiSchema::reference("User"),
             None,
             "application/json",

volga-open-api/src/registry.rs

@@ -364,11 +364,13 @@ mod tests {
         let registry = OpenApiRegistry::new(OpenApiConfig::new().with_specs([OpenApiSpec::new("v1")]));
 
         let first = OpenApiRouteConfig::default().with_response_schema(
+            200u16,
             crate::schema::OpenApiSchema::object()
                 .with_title("User")
                 .with_property("name", crate::schema::OpenApiSchema::string()),
         );
         let second = OpenApiRouteConfig::default().with_response_schema(
+            200u16,
             crate::schema::OpenApiSchema::object()
                 .with_title("User")
                 .with_property("id", crate::schema::OpenApiSchema::integer()),