Annotations

Annotations are specially-structured comments used in your plumber file to create an API. A full annotation line starts with #* or #', then the annotation keyword @..., any number of space characters followed by the content. It is recommended to use #* to differentiate them from Roxygen2 annotations.

Global annotations

Global annotations can be used anywhere in your plumber file. They are independent from other annotations and do not require an expression.

Annotation Argument Description/References
@apiTitle Title Info Object
@apiDescription Description Info Object
@apiTOS TOS link Info Object
@apiContact Contact object Contact Object
@apiLicense License object License Object
@apiVersion Version Info Object
@apiTag Tag Description Can be repeated to add multiple tags. Tag Object
Annotations example
#* @apiTitle Sample Pet Store App
#* @apiDescription This is a sample server for a pet store.
#* @apiTOS http://example.com/terms/
#* @apiContact list(name = "API Support", url = "http://www.example.com/support", email = "support@example.com")
#* @apiLicense list(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0.html")
#* @apiVersion 1.0.1
#* @apiTag pet Pets operations
#* @apiTag toy Toys operations
Equivalent programmatic usage
pr() %>%
  pr_set_api_spec(function(spec) {
    spec$info <- list(
      title = "Sample Pet Store App",
      description = "This is a sample server for a pet store.",
      termsOfService = "http://example.com/terms/",
      contact = list(name = "API Support", url = "http://www.example.com/support", email = "support@example.com"),
      license = list(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0.html"),
      version = "1.0.1"
    )
    spec$tags <- list(list(name = "pet", description = "Pets operations"), list(name = "toy", description = "Toys operations"))
    spec
  })

Block annotations

A block of annotations is a combination of annotations that create either an endpoint, a filter, a static file handler or a Plumber object modifier. Block annotations are always followed by an expression.

Endpoint

Annotation Argument Description/References
@get, @post, @put, @use, @delete, @head, @options, @patch Path Endpoints, Dynamic Routes, Typed Dynamic Routes
@serializer Alias [Args list]] Some serializers accept arguments. See serializers article and serializers reference. Aliases : bmp, cat, contentType, csv, device, feather, format, html, htmlwidget, jpeg, json, null, pdf, png, print, rds, svg, text, tiff, tsv, unboxedJSON, yaml from registered_serializers().
@parser Alias [Args list] Some parsers accept arguments. See parsers reference. Can be repeated to allow multiple parsers on the same endpoint. Aliases : all, csv, feather, form, json, multi, none, octet, rds, text, tsv, yaml from registered_parsers().
@param Name[:Type Description] Enclose Type between square brackets [] to indicate it is an array. Can be repeated to define different parameters.
@response Name Description Simple Response object. Can be repeated to define different responses.
@tags Tag Can be repeated to add multiple tags. Tag field
@preempt Filter Specify that this endpoint has to execute before Filter. Filters
None Comments Lines without annotation will be mapped to Summary field.

More details on @param

Types are used to define API inputs. You can use most of them in dynamic routes. Note that Plumber first look in block expression to set endpoint parameters names, types and default value. Then @param annotations and dynamic route/path defined parameters will override Plumber guesses from block expression.

Plumber parameter type to OpenAPI type refenrence. For programmatic use, pick the one with an asterisk.

Type OpenApi Availability
bool, boolean*, logical boolean query, path
dbl, double, float, number*, numeric number format:double query, path
int, integer* integer format:int64 query, path
chr, str, character, string* string query, path
list, data.frame, df, object* object body
file*, binary string format:binary body
Annotations example
#* @get /dyn/<name:str>/<age:[int]>/route
#* @serializer text
#* @parser none
#* @response 200 A sentence
function(name, age) {
  sprintf("%s is %i years old", name, age)
}

#* @post /upload_file
#* @serializer rds
#* @parser multi
#* @parser rds
#* @param f:file A file
#* Upload an rds file and return the object
function(f) {
  as_attachment(f[[1]], names(f)[1])
}
Equivalent programmatic usage
text_handler <- function(name, age) { sprintf("%s is %i years old", name, age) }
file_handler <- function(file) { as_attachment(file[[1]], names(file)[1]) }
pr() %>%
  pr_get(path = "/dyn/<name:str>/<age:[int]>/route", 
         handler = text_handler, 
         serializer = serializer_text(),
         parsers = "none",
         responses = list("200" = list(description = "A sentence"))) %>%
  pr_post(path = "/upload_file",
          handler = file_handler,
          serializer = serializer_rds(),
          parsers = c("multi", "rds"),
          params = list("file" = list(type = "file", desc = "A file", required = FALSE, isArray = FALSE)),
          comments = "Upload an rds file and return the object")

Filter

Annotation Argument Description/References
@filter Filter name Filters
Annotations example
#* @filter logger
function(req){
  cat(as.character(Sys.time()), "-",
    req$REQUEST_METHOD, req$PATH_INFO, "-",
    req$HTTP_USER_AGENT, "@", req$REMOTE_ADDR, "\n")
  plumber::forward()
}
Equivalent programmatic usage
pr() %>%
  pr_filter("logger", function(req){
    cat(as.character(Sys.time()), "-",
      req$REQUEST_METHOD, req$PATH_INFO, "-",
      req$HTTP_USER_AGENT, "@", req$REMOTE_ADDR, "\n")
    plumber::forward()
  })

Static File Handler

Annotation Arguments Description/References
@assets Directory [Mount path] Static files
Annotations example
#* @assets ./files/static
list()

#* @assets ./files/static /static
list()

#* @assets ./files/static /
list()
Equivalent programmatic usage (note that argument order is reversed)
pr() %>%
  pr_static(direc = "./files/static")

pr() %>%
  pr_static("/static", "./files/static")

pr() %>%
  pr_static("/", "./files/static")

Plumber Object Modifier

Annotation Arguments Description/References
@plumber None Modify plumber router from plumber file.
Annotations example
#* @plumber
function(pr) {
  pr %>%
    pr_set_debug(TRUE) %>%
    pr_set_docs("swagger")
}
Equivalent programmatic usage
pr() %>%
  pr_set_debug(TRUE) %>%
  pr_set_docs("swagger")