Interface mount

DESCRIPTION

@@ -79,6 +79,7 @@ Collate:
     'serializer-yaml.R'
     'serializer.R'
     'session-cookie.R'
+    'ui.R'
     'utf8.R'
     'zzz.R'
 RoxygenNote: 7.1.0

NAMESPACE

@@ -4,6 +4,7 @@ export(PlumberEndpoint)
 export(PlumberStatic)
 export(addParser)
 export(addSerializer)
+export(add_ui)
 export(do_configure_https)
 export(do_deploy_api)
 export(do_forward)

NEWS.md

@@ -18,27 +18,32 @@ plumber 1.0.0
   API were using encrypted cookies and an attacker knew the encryption key in
   order to craft arbitrary cookies. (#325)
 
-
 ### Breaking changes
 
-* Plumber's swagger definition is now defined using
-  [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md),
+* Plumber's OpenAPI Specification is now defined using
+  [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md),
   upgrading from Swagger Specification. (#365)
 
+* Plumber router `$run()` method arguments `swagger` and `swaggerCallback` deprecated. Parameter `swaggerCallback` replaced by `callback`. User interface is now enabled by default and managed through Plumber router `$setUI()` method and option `plumber.ui`. (@meztez, #562)
+
 * The source files used in plumber **must use** the UTF-8 encoding if they contain
   non-ASCII characters (@shrektan, #312,
   #328).
 
 * R repository modified to `focal-cran40` using Ubuntu 20.04 LTS for digital ocean provisioning (@meztez, #529)
 
-
 ### New features
 
+* Generalize user interface integration. Plumber can now use other OpenAPI compatible user interfaces like `RapiDoc` (https://github.com/mrin9/RapiDoc) and `Redoc` (https://github.com/Redocly/redoc). Pending CRAN approbations, R packages for
+both UIs integration are available from https://github.com/meztez/rapidoc/ and https://github.com/meztez/redoc/. (@meztez, #562)
+
 * Added support for promises in endpoints, filters, and hooks. (#248)
 
 * Add support for `#' @plumber` tag to gain programmatic access to the `plumber` router via `function(pr) {....}`. (@meztez and @blairj09, #568)
 
-* Added Swagger support for array parameters using syntax `name:[type]` and new type `list` (synonym df, data.frame). (@meztez, #532)
+* Added OpenAPI support for array parameters using syntax `name:[type]` and new type `list` (synonym df, data.frame). (@meztez, #532)
+
+* Added user provided OpenAPI Specification handler to Plumber router. Use `apiSpecTransform()` to provide a function to alter the Plumber generated OpenAPI Specification returned by Plumber router method `$apiSpec()`. This also affects `/openapi.json` and `/openapi.yaml` (#365)(@meztez, #562)
 
 * Added support to a router's run method to allow the `swagger` parameter to be a function that
   enhances the existing swagger specification before being returned to `/openapi.json`. (#365)
@@ -105,7 +110,6 @@ plumber 1.0.0
 * Date response header is now supplied by httpuv and not plumber. Fixes non standard date response header issues when using different locales. (@shrektan, #319, #380)
 
 
-
 plumber 0.4.6
 --------------------------------------------------------------------------------
 * BUGFIX: Hooks that accept a `value` argument (`postroute`, `preserialize`,

R/globals.R

@@ -2,3 +2,4 @@
 .globals$serializers <- list()
 .globals$processors <- new.env()
 .globals$parsers <- list(func = list(), pattern = list())
+.globals$UIs <- list()

R/openapi-spec.R

@@ -13,10 +13,12 @@ endpointSpecification <- function(routerEndpointEntry, path = routerEndpointEntr
 
   # Get the params from the path
   pathParams <- routerEndpointEntry$getTypedParams()
-  # Get the params from endpoint func
+  # Get the params from endpoint expression
   funcParams <- routerEndpointEntry$getFuncParams()
+  # Get the plumber decoration defined endpoint params
+  endpointParams <- routerEndpointEntry$getEndpointParams()
   for (verb in routerEndpointEntry$verbs) {
-    params <- parametersSpecification(routerEndpointEntry$params, pathParams, funcParams)
+    params <- parametersSpecification(endpointParams, pathParams, funcParams)
 
     # If we haven't already documented a path param, we should add it here.
     # FIXME: warning("Undocumented path parameters: ", paste0())

R/plumber-options.R

@@ -1,60 +1,84 @@
-
-#' How to use Plumber options
+#' Plumber options
 #'
-#' @section Options:
 #' There are a number of global options that affect Plumber's behavior. These can
 #' be set globally with [options()] or with [options_plumber()]. Options set using
 #' [options_plumber()] should not include the `plumber.` prefix.
 #'
 #' \describe{
-#' \item{`plumber.apiHost` (defaults to `host` defined by `run` method, or an empty string
-#' when used outside a running router)}{Host used to build UI url and server url for
-#' OpenAPI specification.}
-#' \item{`plumber.debug` (defaults to `FALSE`)}{Provides more insight into your API errors. Alternatively,
-#' use parameter `debug` of plumber router `run` method}
-#' \item{`plumber.maxRequestSize` (defaults to `0`)}{Maximum length in bytes of request body. Body larger
-#' than maximum are rejected with http error 413. `0` means unlimited size.}
-#' \item{`plumber.postBody` (defaults to `TRUE`)}{Copy post body content to `req$postBody` using system encoding.
+#' \item{`plumber.apiURL`}{UI url and server urls for OpenAPI Specification respecting
+#' pattern `scheme://host:port/path`. Other UI url options will be ignored when set.}
+#' \item{`plumber.apiScheme`}{Scheme used to build UI url and server url for
+#' OpenAPI Specification. Defaults to `http`, or an empty string
+#' when used outside a running router}
+#' \item{`plumber.apiHost`}{Host used to build UI url and server url for
+#' OpenAPI Specification. Defaults to `host` defined by `run` method, or an empty string
+#' when used outside a running router}
+#' \item{`plumber.apiPort`}{Port used to build UI url and server url for
+#' OpenAPI Specification. Defaults to `port` defined by `run` method, or an empty string
+#' when used outside a running router}
+#' \item{`plumber.apiPath`}{Path used to build UI url and server url for
+#' OpenAPI Specification. Defaults to an empty string}
+#' \item{`plumber.debug`}{Provides more insight into your API errors. Alternatively,
+#' use parameter `debug` of plumber router `run` method. Defaults to `FALSE`}
+#' \item{`plumber.maxRequestSize`}{Maximum length in bytes of request body. Body larger
+#' than maximum are rejected with http error 413. `0` means unlimited size. Defaults to `0`}
+#' \item{`plumber.postBody`}{Copy post body content to `req$postBody` using system encoding.
 #' This should be set to `FALSE` if you do not need it. Default is `TRUE` to preserve compatibility with
-#' previous version behavior.}
-#' \item{`plumber.port` (defaults to `NULL`)}{Port Plumber will attempt to use to start http server.
-#' If the port is already in use, server will not be able to start.}
-#' \item{`plumber.sharedSecret` (defaults to `NULL`)}{Shared secret used to filter incoming request.
+#' previous version behavior. Defaults to `TRUE`}
+#' \item{`plumber.port`}{Port Plumber will attempt to use to start http server.
+#' If the port is already in use, server will not be able to start. Defaults to `NULL`}
+#' \item{`plumber.sharedSecret`}{Shared secret used to filter incoming request.
 #' When `NULL`, secret is not validated. Otherwise, Plumber compares secret with http header
-#' `PLUMBER_SHARED_SECRET`. Failure to match results in http error 400.}
-#' \item{`plumber.swagger.url` (defaults to `NULL`)}{A function. Called with
+#' `PLUMBER_SHARED_SECRET`. Failure to match results in http error 400. Defaults to `NULL`}
+#' \item{`plumber.ui`}{Name of the UI interface to use. Defaults to `TRUE`}
+#' \item{`plumber.ui.callback`}{A function. Called with
 #' a single parameter corresponding to ui url after Plumber server is ready. This can be used
-#' by RStudio to open UI when API is ran for the editor.}
+#' by RStudio to open UI when API is ran for the editor. Defaults to option `plumber.swagger.url`}
 #' }
 #'
+#' @param apiScheme see details
 #' @param apiHost see details
+#' @param apiPort see details
+#' @param apiPath see details
+#' @param apiURL see details
 #' @param debug see details
 #' @param maxRequestSize see details
 #' @param postBody see details
 #' @param port see details
 #' @param sharedSecret see details
-#' @param swagger.url see details
+#' @param ui see details
+#' @param ui.callback see details
 #' @return
 #' The complete, prior set of [options()] values.
 #' If a particular parameter is not supplied, it will return the current value.
 #' If no parameters are supplied, all returned values will be the current [options()] values.
 #' @export
 options_plumber <- function(
+  apiScheme            = getOption("plumber.apiScheme"),
   apiHost              = getOption("plumber.apiHost"),
+  apiPort              = getOption("plumber.apiPort"),
+  apiPath              = getOption("plumber.apiPath"),
+  apiURL               = getOption("plumber.apiURL"),
   debug                = getOption("plumber.debug"),
   maxRequestSize       = getOption("plumber.maxRequestSize"),
   postBody             = getOption("plumber.postBody"),
   port                 = getOption("plumber.port"),
   sharedSecret         = getOption("plumber.sharedSecret"),
-  swagger.url          = getOption("plumber.swagger.url")
+  ui                   = getOption("plumber.ui"),
+  ui.callback          = getOption("plumber.ui.callback")
 ) {
   options(
+    plumber.apiScheme = apiScheme,
     plumber.apiHost = apiHost,
+    plumber.apiPort = apiPort,
+    plumber.apiPath = apiPath,
+    plumber.apiURL = apiURL,
     plumber.debug = debug,
     plumber.maxRequestSize = maxRequestSize,
     plumber.postBody = postBody,
     plumber.port = port,
     plumber.sharedSecret = sharedSecret,
-    plumber.swagger.url = swagger.url
+    plumber.ui = ui,
+    plumber.ui.callback = ui.callback
   )
 }

R/plumber-step.R

@@ -228,6 +228,16 @@ PlumberEndpoint <- R6Class(
     #' @description retrieve endpoint expression parameters
     getFuncParams = function() {
       getArgsMetadata(private$func)
+    },
+    #' @description retrieve endpoint defined parameters
+    getEndpointParams = function() {
+      if (length(self$params) == 0) {
+        return(list())
+      }
+      if (isTRUE(is.na(self$params))) {
+        return(list())
+      }
+      self$params
     }
   ),
   private = list(