Plumber: How generate API documentation from R plumber API code?

[andirey]

Let say I have a set of functions for processing API requests

#' Function description
#' @get /list
#' @param key Auth key
#' @param user User ID
#' @example https://api.company.com/list?key=123&user=345
function(key, user) { ... }

Is it possible to generate good API documentation from R code? Or maybe there is another way to do it?

Thanks

Andrii

[meztez]

@andirey Thanks for your question.

Are you having an issue with the plumber package or is it a usability question?

What is the expected behavior?

[andirey]

This is an issue about using a "plumber" on production. I am R and R Shiny developer, and one of my applications has a REST API server made on the "plumber". Right now I need to share documentation on how to use this API. I am looking for a way to generate it from existed API functions but it seems impossible now. Do you have any recommendations on how to generate or design nice-looking documentation for plumber-based API? Thanks!

[meztez]

plumber already generate openapi documentation available at the root of your router /openapi.json

Look at parameter docs in run.

Not sure if that answer your question.

[meztez]

When you run a plumber API with docs set to TRUE, you should see something like

> plumber::plumb(file='C:/Users/user001/Work/plumber.R')$run()
Running plumber API at http://127.0.0.1:5297
Running swagger Docs at http://127.0.0.1:5297/__docs__/

The API doc is available at http://127.0.0.1:5297/__docs__/

See
https://www.rplumber.io/reference/pr_run.html
https://neoxone.com/2021/01/31/plumber-v1-0-showcase-part-1/

[andirey]

Thanks a lot for the detailed answer.

Here is the code I used now:

pr <- plumber::plumb("apicode.R")
pr$run(host="127.0.0.1", port = 9090, swagger = FALSE)

If I set "swagger" to TRUE - is it the solution to get doc on http://127.0.0.1:9090/__docs__/ ?

[meztez]

By setting swagger to FALSE, you are disabling the automated UI interface playground but the API OpenAPI spec is still available at http://127.0.0.1:9090/openapi.json.

Setting swagger to TRUE (swagger is now deprecated, latest version uses docs) will make an interactive UI available to play with your API.

This is the generic plumber startup we use in production, the plumber.R file is in the same location as the startup file. Plus we use an environment variable to trigger DEBUG log-level.

library(plumber)

pr <- plumb()
postroute = function(req) {
  if (req$REQUEST_METHOD == "POST") {
      cat("[", req$REQUEST_METHOD, req$PATH_INFO, "] - REQUEST - ", req$postBody, "\n", sep = "")
  }
}

postserializewithoutpayload <- function(req, res) {
  if (req$REQUEST_METHOD == "POST") {
    cat("[", req$REQUEST_METHOD, req$PATH_INFO, "] - RESPONSE - ", res$status, "\n", sep = "")
  }
}

postserializewithpayload <- function(req, res) {
  if (req$REQUEST_METHOD == "POST") {
    cat("[", req$REQUEST_METHOD, req$PATH_INFO, "] - RESPONSE - ", res$status, " - BODY - ", res$body, "\n", sep = "")
  }
}

hooklist <- list(postserialize = postserializewithoutpayload)
debughooklist <- list(postserialize = postserializewithpayload, postroute = postroute)

if (Sys.getenv("DBG_ENABLE", FALSE) == TRUE) {
  pr$setDebug(TRUE)
  pr$registerHooks(debughooklist)
} else {
  pr$registerHooks(hooklist)
}

pr$run(host = "0.0.0.0", port = 8004)