From 161bff9fed6976979732f7901484dd3e9fad2caf Mon Sep 17 00:00:00 2001
From: wkmor1 <1680870+wkmor1@users.noreply.github.com>
Date: Tue, 18 May 2021 17:17:47 +0000
Subject: [PATCH] Add endpoint description to API spec

---
 NEWS.md                           | 5 ++++-
 R/openapi-spec.R                  | 1 +
 R/plumb-block.R                   | 4 +++-
 R/plumber-step.R                  | 9 +++++++--
 man/PlumberEndpoint.Rd            | 5 ++++-
 tests/testthat/test-parse-block.R | 6 +++++-
 vignettes/annotations.Rmd         | 2 +-
 7 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 4c9b0ce4..4881ddd9 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,7 +2,10 @@
 
 ## Breaking changes
 
-## New features
+* First line of endpoint comments interpreted as OpenAPI 'summary' field and subsequent comment lines interpreted as 'description' field.
+
+## New features 
+
 ## Bug fixes
 
 * OpenAPI response type detection had a scoping issue. Use serializer defined `Content-Type` header instead. (@meztez, #789)
diff --git a/R/openapi-spec.R b/R/openapi-spec.R
index 8b4a635a..364ed115 100644
--- a/R/openapi-spec.R
+++ b/R/openapi-spec.R
@@ -27,6 +27,7 @@ endpointSpecification <- function(routerEndpointEntry, path = routerEndpointEntr
 
     endptSpec <- list(
       summary = routerEndpointEntry$comments,
+      description = routerEndpointEntry$description,
       responses = resps,
       parameters = params$parameters,
       requestBody = params$requestBody,
diff --git a/R/plumb-block.R b/R/plumb-block.R
index 501949cd..af490ced 100644
--- a/R/plumb-block.R
+++ b/R/plumb-block.R
@@ -250,7 +250,8 @@ plumbBlock <- function(lineNum, file, envir = parent.frame()){
     parsers = rev(parsers),
     assets = assets,
     params = rev(params),
-    comments = paste0(rev(comments), collapse = " "),
+    comments = paste0(rev(comments)[1], collapse = " "),
+    description = paste0(rev(comments)[-1], collapse = " "),
     responses = rev(responses),
     tags = rev(tags),
     routerModifier = routerModifier
@@ -283,6 +284,7 @@ evaluateBlock <- function(srcref, file, expr, envir, addEndpoint, addFilter, pr)
         srcref = srcref,
         params = block$params,
         comments = block$comments,
+        description = block$description,
         responses = block$responses,
         tags = block$tags
       )
diff --git a/R/plumber-step.R b/R/plumber-step.R
index a94fa831..400b4cd0 100644
--- a/R/plumber-step.R
+++ b/R/plumber-step.R
@@ -181,6 +181,8 @@ PlumberEndpoint <- R6Class(
     path = NA,
     #' @field comments endpoint comments
     comments = NA,
+    #' @field description endpoint description
+    description = NA,
     #' @field responses endpoint responses
     responses = NA,
     #' @description retrieve endpoint typed parameters
@@ -220,11 +222,11 @@ PlumberEndpoint <- R6Class(
     #' @param srcref `srcref` attribute from block
     #' @param lines Endpoint block
     #' @param params Endpoint params
-    #' @param comments,responses,tags Values to be used within the OpenAPI Spec
+    #' @param comments,description,responses,tags Values to be used within the OpenAPI Spec
     #' @details Parameters values are obtained from parsing blocks of lines in a plumber file.
     #' They can also be provided manually for historical reasons.
     #' @return A new `PlumberEndpoint` object
-    initialize = function(verbs, path, expr, envir, serializer, parsers, lines, params, comments, responses, tags, srcref) {
+    initialize = function(verbs, path, expr, envir, serializer, parsers, lines, params, comments, description, responses, tags, srcref) {
 
       self$verbs <- verbs
 
@@ -258,6 +260,9 @@ PlumberEndpoint <- R6Class(
       if (!missing(comments)){
         self$comments <- comments
       }
+      if (!missing(description)){
+        self$description <- description
+      }
       if (!missing(responses)){
         self$responses <- responses
       }
diff --git a/man/PlumberEndpoint.Rd b/man/PlumberEndpoint.Rd
index 0aa9a3b2..eb59c7f3 100644
--- a/man/PlumberEndpoint.Rd
+++ b/man/PlumberEndpoint.Rd
@@ -28,6 +28,8 @@ each separate verb/path into its own endpoint, so we just do that.}
 
 \item{\code{comments}}{endpoint comments}
 
+\item{\code{description}}{endpoint description}
+
 \item{\code{responses}}{endpoint responses}
 
 \item{\code{params}}{endpoint parameters}
@@ -128,6 +130,7 @@ Create a new \code{PlumberEndpoint} object
   lines,
   params,
   comments,
+  description,
   responses,
   tags,
   srcref
@@ -175,7 +178,7 @@ parsers = c("json", "form", "text", "octet", "multi")
 
 \item{\code{params}}{Endpoint params}
 
-\item{\code{comments, responses, tags}}{Values to be used within the OpenAPI Spec}
+\item{\code{comments, description, responses, tags}}{Values to be used within the OpenAPI Spec}
 
 \item{\code{srcref}}{\code{srcref} attribute from block}
 }
diff --git a/tests/testthat/test-parse-block.R b/tests/testthat/test-parse-block.R
index 426501d4..1abf2eee 100644
--- a/tests/testthat/test-parse-block.R
+++ b/tests/testthat/test-parse-block.R
@@ -11,6 +11,8 @@ test_that("plumbBlock works", {
     "#* Plumber comment not reached",
     "NULL",
     "#* Plumber comments",
+    "#* Plumber description",
+    "#* second line",
     "",
     "  ",
     "# Normal comments",
@@ -25,6 +27,7 @@ test_that("plumbBlock works", {
   expect_equal(b$paths[[2]], list(verb="POST", path="/"))
   expect_equal(b$filter, "test")
   expect_equal(b$comments, "Plumber comments")
+  expect_equal(b$description, "Plumber description second line")
 
   # due to covr changing some code, the return answer is very strange
   # the tests below should be skipped on covr
@@ -281,10 +284,11 @@ test_that("block respect original order of lines for comments, tags and response
     "#' @tag bbb",
     "#' comments first line",
     "#' comments second line",
+    "#' comments third line",
     "#' @response 200 ok",
     "#' @response 404 not ok")
   b <- plumbBlock(length(lines), lines)
-  expect_equal(b$comments, "comments first line comments second line")
+  expect_equal(b$description, "comments second line comments third line")
   expect_equal(b$tags, c("aaa", "bbb"))
   expect_equal(b$responses, list(`200`=list(description="ok"), `404` = list(description="not ok")))
 })
diff --git a/vignettes/annotations.Rmd b/vignettes/annotations.Rmd
index 7b540b28..e5745c8f 100644
--- a/vignettes/annotations.Rmd
+++ b/vignettes/annotations.Rmd
@@ -76,7 +76,7 @@ Annotation | Argument | Description/References
 `@response` | `Name` `Description` | Simple [Response object](http://spec.openapis.org/oas/v3.0.3#response-object). Can be repeated to define different responses.
 `@tag` | `Tag` | Can be repeated to add multiple tags. Quote with " or ' to use non word character (like spaces) in `Tag`. [Tag field](http://spec.openapis.org/oas/v3.0.3#operation-object)
 `@preempt` | `Filter` | Specify that this endpoint has to execute before `Filter`. [Filters](./programmatic-usage.html#defining-filters)
-None | `Comments` | Lines without annotation will be mapped to [Summary field](http://spec.openapis.org/oas/v3.0.3#fixed-fields-6).
+None | `Comments` | First line without annotation will be mapped to [Summary field](http://spec.openapis.org/oas/v3.0.3#fixed-fields-6) subsequent lines will be mapped to [Description field](http://spec.openapis.org/oas/v3.0.3#fixed-fields-6).
 
 
 #### More details on `@param`