api_docs: Configure your API for serving documentation for itself

In plumber2: Easy and Powerful Web Servers

Configure your API for serving documentation for itself

Description

The OpenAPI standard offers a way to describe the various endpoints of your api in machine- and human-readable way. On top of this, various solutions have been build to generate online documentation of the API based on a provided OpenAPI spec. plumber2 offers support for RapiDoc, Redoc, and Swagger as a UI frontend for the documentation and will also generate the spec for you based on the tags in parsed files. If you are creating your API programmatically or you wish to add to the autogenerated docs you can add docs manually, either when adding a handler (using the doc argument), or with the api_doc_add() function

Usage

api_doc_setting(api, doc_type, doc_path, ...)

api_doc_add(api, doc, overwrite = FALSE, subset = NULL)

Arguments

api	A plumber2 api object to add docs or doc settings to
doc_type	The type of API documentation to generate. Can be either "rapidoc" (the default), "redoc", "swagger", or NULL (equating to not generating API docs)
doc_path	The URL path to serve the api documentation from
...	plumber files or directories containing plumber files to be parsed in the given order. The order of parsing determines the final order of the routes in the stack. If ... contains a ⁠_server.yml⁠ file then all other files in ... will be ignored and the ⁠_server.yml⁠ file will be used as the basis for the API
doc	A list with the OpenAPI documentation, usually constructed with one of the helper functions
overwrite	Logical. Should already existing documentation be removed or should it be merged together with doc
subset	A character vector giving the path to the subset of the docs to assign doc to

Value

These functions return the api object allowing for easy chaining with the pipe

Using annotation

When using annotated route files documentation is automatically generated based on the annotation. The following tags will contribute to documentation:

• ⁠@title⁠

• ⁠@description⁠

• ⁠@details⁠

• ⁠@tos⁠

• ⁠@license⁠

• ⁠@contact⁠

• ⁠@tag⁠

• ⁠@param⁠

• ⁠@query⁠

• ⁠@body⁠

• ⁠@response⁠

• ⁠@parsers⁠

• ⁠@serializers⁠

Documentation is only generated for annotations related to global documentation (a block followed by the "_API" sentinel), request handlers (a block including one of ⁠@get⁠, ⁠@head⁠, ⁠@post⁠, ⁠@put⁠, ⁠@delete⁠, ⁠@connect⁠, ⁠@options⁠, ⁠@trace⁠, ⁠@patch⁠, or ⁠@any⁠), or report generation (a block including ⁠@report⁠)

Examples

# Serve the docs from a different path
api() |>
  api_doc_setting(doc_path = "__man__")

# Add documentation to the api programmatically
api() |>
  api_doc_add(openapi(
    info = openapi_info(
      title = "My awesome api",
      version = "1.0.0"
    )
  ))

# Add documentation to a subset of the docs
api() |>
  api_doc_add(
    openapi_operation(
      summary = "Get the current date",
      responses = list(
        "200" = openapi_response(
          description = "Current Date",
          content = openapi_content(
            "text/plain" = openapi_schema(character())
          )
        )
      )
    ),
    subset = c("paths", "/date", "get")
  )

plumber2 documentation built on Jan. 20, 2026, 5:06 p.m.