Introduce structured and unstructured response headers (#283)

Author: ahl

CHANGELOG.adoc

@@ -25,6 +25,7 @@ https://github.com/oxidecomputer/dropshot/compare/v0.6.0\...HEAD[Full list of co
 * https://github.com/oxidecomputer/dropshot/pull/198[#198] Responses that used `()` (the unit type) as their `Body` type parameter previously (and inaccurately) were represented in OpenAPI as an empty `responseBody`. They are now more accurately represented as a body whose value is `null` (4 bytes). We encourage those use cases to instead use either `HttpResponseUpdatedNoContent` or `HttpResponseDeleted` both of which have empty response bodies. If there are other situations where you would like a response type with no body, please file an issue.
 * https://github.com/oxidecomputer/dropshot/pull/252[#252] Endpoints specified with the `#[endpoint ..]` attribute macro now use the first line of a doc comment as the OpenAPI `summary` and subsequent lines as the `description`. Previously all lines were used as the `description`.
 * https://github.com/oxidecomputer/dropshot/pull/260[#260] Pulls in a newer serde that changes error messages around parsing NonZeroU32.
+* https://github.com/oxidecomputer/dropshot/pull/283[#283] Add support for response headers with the `HttpResponseHeaders` type. Headers may either be defined by a struct type parameter (in which case they appear in the OpenAPI output) or *ad-hoc* added via `HttpResponseHeaders::headers_mut()`.
 
 == 0.6.0 (released 2021-11-18)
 

dropshot/src/api_description.rs

@@ -134,17 +134,16 @@ impl ApiEndpointParameter {
 
     pub fn new_body(
         content_type: ApiEndpointBodyContentType,
-        description: Option<String>,
         required: bool,
         schema: ApiSchemaGenerator,
         examples: Vec<String>,
     ) -> Self {
         Self {
             metadata: ApiEndpointParameterMetadata::Body(content_type),
-            description,
             required,
             schema,
             examples,
+            description: None,
         }
     }
 }
@@ -179,12 +178,21 @@ impl ApiEndpointBodyContentType {
     }
 }
 
+#[derive(Debug)]
+pub struct ApiEndpointHeader {
+    pub name: String,
+    pub description: Option<String>,
+    pub schema: ApiSchemaGenerator,
+    pub required: bool,
+}
+
 /**
  * Metadata for an API endpoint response: type information and status code.
  */
-#[derive(Debug)]
+#[derive(Debug, Default)]
 pub struct ApiEndpointResponse {
     pub schema: Option<ApiSchemaGenerator>,
+    pub headers: Vec<ApiEndpointHeader>,
     pub success: Option<StatusCode>,
     pub description: Option<String>,
 }
@@ -603,6 +611,45 @@ impl<Context: ServerContext> ApiDescription<Context> {
                     );
                 }
 
+                let headers = endpoint
+                    .response
+                    .headers
+                    .iter()
+                    .map(|header| {
+                        let schema = match &header.schema {
+                            ApiSchemaGenerator::Static {
+                                schema,
+                                dependencies,
+                            } => {
+                                definitions.extend(dependencies.clone());
+                                j2oas_schema(None, schema)
+                            }
+                            _ => {
+                                unimplemented!(
+                                    "this may happen for complex types"
+                                )
+                            }
+                        };
+
+                        (
+                            header.name.clone(),
+                            openapiv3::ReferenceOr::Item(openapiv3::Header {
+                                description: header.description.clone(),
+                                style: openapiv3::HeaderStyle::Simple,
+                                required: header.required,
+                                deprecated: None,
+                                format:
+                                    openapiv3::ParameterSchemaOrContent::Schema(
+                                        schema,
+                                    ),
+                                example: None,
+                                examples: indexmap::IndexMap::new(),
+                                extensions: indexmap::IndexMap::new(),
+                            }),
+                        )
+                    })
+                    .collect();
+
                 let response = openapiv3::Response {
                     description: if let Some(description) =
                         &endpoint.response.description
@@ -614,7 +661,8 @@ impl<Context: ServerContext> ApiDescription<Context> {
                         // by OpenAPI.
                         "".to_string()
                     },
-                    content: content,
+                    content,
+                    headers,
                     ..Default::default()
                 };