plumber2 (version 0.2.0)

api_docs: 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)

Value

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

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

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")
  )