Merge branch 'main' into rc-v1.3.0

* main:
  bug: Validate APIs using `@redocly/cli` (#986)

Author: schloerke

NAMESPACE

@@ -110,6 +110,7 @@ export(validate_api_spec)
 import(R6)
 import(promises)
 import(stringi)
+importFrom(crayon,silver)
 importFrom(grDevices,dev.cur)
 importFrom(grDevices,dev.set)
 importFrom(jsonlite,parse_json)

NEWS.md

@@ -14,12 +14,18 @@
 
 * Mounts now have a dynamic `req$PATH_INFO` instead of a pre-computed value. (#888)
 
+* `validate_api_spec()` now uses `@redocly/cli` to validate the API spec. (#986)
+
+* Added `operationId` to each operation within the auto-generated OpenAPI output. The value is similar to the `PATH-VERB`, e.g. `/users/create-POST`. (#986)
+
+
 # plumber 1.2.2
 
 * Allow to set plumber options using environment variables `?options_plumber`. (@meztez #934)
 * Add support for quoted boundary for multipart request parsing. (@meztez #924)
 * Fix #916, related to `parseUTF8` return value attribute `srcfile` on Windows. (#930)
 
+
 # plumber 1.2.1
 
 * Update docs for CRAN (#878)

R/openapi-spec.R

@@ -26,6 +26,7 @@ endpointSpecification <- function(routerEndpointEntry, path = routerEndpointEntr
     resps <- responsesSpecification(routerEndpointEntry)
 
     endptSpec <- list(
+      operationId = paste0(cleanedPath, "-", verb),
       summary = routerEndpointEntry$comments,
       description = routerEndpointEntry$description,
       responses = resps,

R/utils.R

@@ -1,3 +1,6 @@
+#' @importFrom crayon silver
+NULL
+
 #' HTTP Date String
 #'
 #' Given a POSIXct object, return a date string in the format required for a

R/validate_api_spec.R

@@ -1,73 +1,34 @@
-
-#' @include globals.R
-validate_api_spec_folder <- function() {
-  file.path(tempdir(), "plumber_validate_api_spec")
-}
-
-
-validate_api_spec__install_node_modules <- function() {
-
-  if (!nzchar(Sys.which("node"))) {
-    stop("node not installed")
-  }
-  if (!nzchar(Sys.which("npm"))) {
-    stop("npm not installed")
-  }
-
-  if (dir.exists(validate_api_spec_folder())) {
-    # assume npm install has completed
-    return(invisible(TRUE))
-  }
-
-  dir.create(validate_api_spec_folder(), recursive = TRUE, showWarnings = FALSE)
-
-  file.copy(
-    system.file(file.path("validate_api_spec", "package.json"), package = "plumber"),
-    file.path(validate_api_spec_folder(), "package.json")
-  )
-
-  old_wd <- setwd(validate_api_spec_folder())
-  on.exit({
-    setwd(old_wd)
-  }, add = TRUE)
-
-  # install everything. Ignore regular output
-  status <- system2("npm", c("install", "--loglevel", "warn"), stdout = FALSE)
-  if (status != 0) {
-      # delete the folder if it didn't work
-      unlink(validate_api_spec_folder(), recursive = TRUE)
-      stop("Could not install npm dependencies required for plumber::validate_api_spec()")
-  }
-
-  invisible(TRUE)
-}
-
-
 #' Validate OpenAPI Spec
 #'
-#' Validate an OpenAPI Spec using [Swagger CLI](https://github.com/APIDevTools/swagger-cli) which calls [Swagger Parser](https://github.com/APIDevTools/swagger-parser).
+#' Validate an OpenAPI Spec using [`@redocly/cli`](https://redocly.com/docs/cli/commands/lint).
 #'
-#' If the api is deemed invalid, an error will be thrown.
+#' If any warning or error is presented, an error will be thrown.
 #'
-#' This function is VERY `r lifecycle::badge("experimental")` and may be altered, changed, or removed in the future.
+#' This function is `r lifecycle::badge("experimental")` and may be altered, changed, or removed in the future.
 #'
 #' @param pr A Plumber API
+#' @param ... Ignored
+#' @param ruleset Character that determines the ruleset to use for validation. Can be one of "minimal", "recommended",
+#' or "recommended-strict". Defaults to "minimal". See [`@redocly/cli`
+#' options](https://redocly.com/docs/cli/commands/lint#options) for more details.
 #' @param verbose Logical that determines if a "is valid" statement is displayed. Defaults to `TRUE`
 #' @export
 #' @examples
 #' \dontrun{
 #' pr <- plumb_api("plumber", "01-append")
 #' validate_api_spec(pr)
 #' }
-validate_api_spec <- function(pr, verbose = TRUE) {
-
-  validate_api_spec__install_node_modules()
+validate_api_spec <- function(pr, ..., ruleset = c("minimal", "recommended", "recommended-strict"), verbose = TRUE) {
 
+  ruleset <- match.arg(ruleset, several.ok = FALSE)
+  if (!nzchar(Sys.which("node"))) {
+    stop("`node` command not found. Please install Node.js")
+  }
+  if (!nzchar(Sys.which("npx"))) {
+    stop("`npx` not installed. Please install Node.js w/ `npx` command available.")
+  }
+  
   spec <- jsonlite::toJSON(pr$getApiSpec(), auto_unbox = TRUE, pretty = TRUE)
-  old_wd <- setwd(validate_api_spec_folder())
-  on.exit({
-    setwd(old_wd)
-  }, add = TRUE)
 
   tmpfile <- tempfile(fileext = ".json")
   on.exit({
@@ -76,27 +37,31 @@ validate_api_spec <- function(pr, verbose = TRUE) {
   cat(spec, file = tmpfile)
 
   output <- system2(
-    "node_modules/.bin/swagger-cli",
+    "npx",
     c(
-      "validate",
+      "--yes", # auto install `@redocly/cli`
+      "-p", "@redocly/cli",
+      "redocly",
+      "lint",
+      "--extends", ruleset,
+      "--skip-rule", "no-empty-servers", # We don't know the end servers by default
+      "--skip-rule", "security-defined", # We don't know the security by default
+      "--skip-rule", "operation-summary", # operation summary values are optional. Not required
+      "--skip-rule", "operation-operationId-url-safe", # By default, it wants to have all operationId values be URL safe. This does not work with path parameters that want to use `{``}`.
+      "--skip-rule", "no-path-trailing-slash", # This is OK
       tmpfile
     ),
     stdout = TRUE,
     stderr = TRUE
   )
-
+  
   output <- paste0(output, collapse = "\n")
 
-  # using expect_equal vs a regex test to have a better error message
-  is_equal <- sub(tmpfile, "", output, fixed = TRUE) == " is valid"
-  if (!isTRUE(is_equal)) {
-    cat("Plumber Spec: \n", as.character(spec), "\nOutput:\n", output)
+  has_warn_or_error <- grepl("\n[1] ", output, fixed = TRUE)
+  if (has_warn_or_error) {
+    cat("Plumber Spec: \n", as.character(spec), "\n\nOutput:\n", output, sep = "")
     stop("Plumber OpenAPI Spec is not valid")
   }
 
-  if (isTRUE(verbose)) {
-    cat(crayon::green("\u2714"), crayon::silver(": Plumber OpenAPI Spec is valid"), "\n", sep = "")
-  }
-
   invisible(TRUE)
 }

inst/WORDLIST

@@ -2,7 +2,6 @@ API's
 Api
 BMP
 BUGFIX
-CLI
 CORS
 CentOS
 Crypto
@@ -125,6 +124,7 @@ repo
 req
 retransmitted
 rstudio
+ruleset
 runnable
 scalability
 scalable

inst/validate_api_spec/package.json

@@ -72,7 +72,7 @@ Annotation | Argument | Description/References
 `@get`, `@post`, `@put`, `@use`, `@delete`, `@head`, `@options`, `@patch` | `Path` | [Endpoints](./routing-and-input.html#endpoints), [Dynamic Routes](./routing-and-input.html#dynamic-routes), [Typed Dynamic Routes](./routing-and-input.html#typed-dynamic-routes)
 `@serializer` | `Alias` [`Args list]`] | Some serializers accept arguments. See [serializers article](./rendering-output.html#serializers) and [serializers reference](https://www.rplumber.io/reference/serializers.html). Aliases : `r paste0("<code>", registered_serializers(), "</code>", collapse = ", ")` from [`registered_serializers()`](https://www.rplumber.io/reference/register_serializer.html).
 `@parser` | `Alias` `[Args list]` | Some parsers accept arguments. See [parsers reference](https://www.rplumber.io/reference/parsers.html). Can be repeated to allow multiple parsers on the same endpoint. Aliases : `r paste0("<code>", registered_parsers(), "</code>", collapse = ", ")` from [`registered_parsers()`](https://www.rplumber.io/reference/register_parser.html).
-`@param` | `Name`[`:Type`(`*`) `Description`] | Enclose `Type` between square brackets `[]` to indicate it is an array. Adding an asterix indicates that the parameter is required. Can be repeated to define different parameters.
+`@param` | `Name`[`:Type`(`*`) `Description`] | Enclose `Type` between square brackets `[]` to indicate it is an array. Adding an asterisk indicates that the parameter is required. Can be repeated to define different parameters.
 `@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)