diff --git a/NEWS.md b/NEWS.md index 26d716ed..2f27925b 100644 --- a/NEWS.md +++ b/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) 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..870e96f3 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 = 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 ) 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 10d3ead9..d1ae360b 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 @@ -177,7 +180,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..d7c914f2 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\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"))) }) diff --git a/vignettes/annotations.Rmd b/vignettes/annotations.Rmd index 46210db8..4174076c 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`