rswaggerswagger-uidocumentation-generationplumber

Descriptions for endpoints in Swagger for Plumber API


The documentation for block annotations for Plumber endpoints in R states the following about comments without an annotation:

First line without annotation will be mapped to Summary field subsequent lines will be mapped to Description field.

I would like to add a more elaborate description for my endpoint, but the result is not as I expected. This is illustrated using the following very basic example.

library(plumber)

#* @apiTitle Plumber Example API
#* @apiDescription Plumber example description.

#* This is the summary.
#* 
#* This should be a description (if I understand correctly). 
#* @param msg The message to echo
#* @get /echo
function(msg = "") {
    list(msg = paste0("The message is: '", msg, "'"))
}

Running this API results in the following in the Swagger UI: Swagger documentation of endpoint

There does not seem to be a distinction between summary and description. The description (highlighted) is rendered on a single line with the summary in the resulting Swagger UI. Based on the answer to this question, which does not use Plumber, I would expect the description to end up between the summary and the "Parameters" section as marked in red.

Am I misunderstanding the documentation or not applying it correctly? Or is this a bug in Plumber?


Solution

  • Apparently, this feature is only supported as of version 1.2.0. So, the documentation I was looking at did not match the package version...