Add endpoint description field to API spec

NEWS.md

@@ -2,7 +2,9 @@
 
 ## Breaking changes
 
-## New features
+* First line of endpoint comments interpreted as OpenAPI 'summary' field and subsequent comment lines interpreted as 'description' field. (@wkmor1 #805)
+
+## New features 
 
 * Static file handler now serves HEAD requests. (#798)
 * Introduces new GeoJSON serializer and parser. GeoJSON objects are parsed into `sf` objects and `sf` or `sfc` objects will be serialized into GeoJSON. (@josiahparry, #830)

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,

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 = tail(comments, 1),
+    description = paste0(rev(comments)[-1], collapse = "\n"),
     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
       )

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
       }

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\nsecond line")
 
   # due to covr changing some code, the return answer is very strange
   # the tests below should be skipped on covr
@@ -281,10 +284,12 @@ 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$comments, "comments first line")
+  expect_equal(b$description, "comments second line\ncomments third line")
   expect_equal(b$tags, c("aaa", "bbb"))
   expect_equal(b$responses, list(`200`=list(description="ok"), `404` = list(description="not ok")))
 })

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`