Populate OpenAPI summary field with first line of endpoint doc commen…

…ts (#252)
oxidecomputer · Jan 21, 2022 · f98d611 · f98d611
1 parent 2559830
commit f98d611
Show file tree

Hide file tree

Showing 8 changed files with 244 additions and 54 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/dropshot/src/api_description.rs b/dropshot/src/api_description.rs
@@ -36,6 +36,7 @@ pub struct ApiEndpoint<Context: ServerContext> {
     pub path: String,
     pub parameters: Vec<ApiEndpointParameter>,
     pub response: ApiEndpointResponse,
+    pub summary: Option<String>,
     pub description: Option<String>,
     pub tags: Vec<String>,
     pub paginated: bool,
@@ -63,13 +64,19 @@ impl<'a, Context: ServerContext> ApiEndpoint<Context> {
             path: path.to_string(),
             parameters: func_parameters.parameters,
             response,
+            summary: None,
             description: None,
             tags: vec![],
             paginated: func_parameters.paginated,
             visible: true,
         }
     }
 
+    pub fn summary<T: ToString>(mut self, description: T) -> Self {
+        self.summary.replace(description.to_string());
+        self
+    }
+
     pub fn description<T: ToString>(mut self, description: T) -> Self {
         self.description.replace(description.to_string());
         self
@@ -465,6 +472,7 @@ impl<Context: ServerContext> ApiDescription<Context> {
             };
             let mut operation = openapiv3::Operation::default();
             operation.operation_id = Some(endpoint.operation_id.clone());
+            operation.summary = endpoint.summary.clone();
             operation.description = endpoint.description.clone();
             operation.tags = endpoint.tags.clone();
 
@@ -812,7 +820,7 @@ fn j2oas_schema_object(
         (None, None) => {
             openapiv3::SchemaKind::Any(openapiv3::AnySchema::default())
         }
-        _ => panic!("invalid"),
+        _ => panic!("invalid {:#?}", obj),
     };
 
     let mut data = openapiv3::SchemaData::default();

diff --git a/dropshot/src/router.rs b/dropshot/src/router.rs
@@ -849,6 +849,7 @@ mod test {
                 success: None,
                 description: None,
             },
+            summary: None,
             description: None,
             tags: vec![],
             paginated: false,

diff --git a/dropshot/tests/test_openapi.json b/dropshot/tests/test_openapi.json
@@ -239,7 +239,8 @@
     },
     "/test/person": {
       "get": {
-        "description": "This is a multi-line comment. It uses Rust-style.",
+        "summary": "Rust style comment",
+        "description": "This is a multi-line comment.",
         "operationId": "handler1",
         "responses": {
           "200": {
@@ -328,7 +329,8 @@
     },
     "/test/woman": {
       "put": {
-        "description": "This is a multi-line comment. It uses C-style.",
+        "summary": "C-style comment",
+        "description": "This is a multi-line comment.",
         "operationId": "handler2",
         "parameters": [
           {

diff --git a/dropshot/tests/test_openapi.rs b/dropshot/tests/test_openapi.rs
@@ -15,9 +15,10 @@ use std::{io::Cursor, str::from_utf8, sync::Arc};
     method = GET,
     path = "/test/person",
 }]
+/// Rust style comment
+///
 /// This is a multi-
 /// line comment.
-/// It uses Rust-style.
 async fn handler1(
     _rqctx: Arc<RequestContext<()>>,
 ) -> Result<HttpResponseOk<()>, HttpError> {
@@ -36,9 +37,10 @@ struct QueryArgs {
     path = "/test/woman",
 }]
 /**
+ * C-style comment
+ *
  * This is a multi-
  * line comment.
- * It uses C-style.
  */
 async fn handler2(
     _rqctx: Arc<RequestContext<()>>,

diff --git a/dropshot/tests/test_openapi_fuller.json b/dropshot/tests/test_openapi_fuller.json
@@ -247,7 +247,8 @@
     },
     "/test/person": {
       "get": {
-        "description": "This is a multi-line comment. It uses Rust-style.",
+        "summary": "Rust style comment",
+        "description": "This is a multi-line comment.",
         "operationId": "handler1",
         "responses": {
           "200": {
@@ -336,7 +337,8 @@
     },
     "/test/woman": {
       "put": {
-        "description": "This is a multi-line comment. It uses C-style.",
+        "summary": "C-style comment",
+        "description": "This is a multi-line comment.",
         "operationId": "handler2",
         "parameters": [
           {

diff --git a/dropshot_endpoint/Cargo.toml b/dropshot_endpoint/Cargo.toml
@@ -13,12 +13,15 @@ proc-macro = true
 [dependencies]
 proc-macro2 = "1"
 quote = "1"
-serde_tokenstream = "0.1.3"
+serde_tokenstream = "0.1"
 
 [dependencies.serde]
 version = "1.0"
 features = [ "derive" ]
 
 [dependencies.syn]
-version = "1.0.85"
+version = "1.0"
 features = [ "parsing", "printing" ]
+
+[dev-dependencies]
+schema = "0.0.1"