View Source ScalarPlug (scalar_plug v0.2.0)

ScalarPlug is an Elixir plug to integrate Scalar into your Elixir application. When a request URL path matches the path the plug has been configured with, it returns a HTML response initializing Scalar.

Installation

The package is available in Hex and you can install it by adding the dependency to your project's mix.exs:

def deps do
  [
    {:scalar_plug, "~> 0.1.0"}
  ]
end

Usage

You can add ScalarPlug as a plug to your project passing the configuration options as a keyword list, or a mfa {:module, :function} to fetch the options at runtime. The following options are supported:

  • path: The path at which the documentation will be served (e.g. /api/docs).
  • spec_href: The path or URL to the OpenAPI specification (e.g. /api/spec).
  • title (optional): The value of the <title> head tag. When absent, the value API Documentation is used.
  • og_title (optional): The value of the <meta property="og-title"> Open Graph tag. When absent, the value of title is used.
  • url (optional): The value of the <meta property="og-url"> and <meta name="twitter:url"> tags. When absent, the value is derived from the plug request.
  • image_url (optional): The value of the <meta property="og-image"> and <meta name="twitter:image"> tags. When absent, the elements are not included.
  • x_handle (optional): The X handle (without the @) to set to the <meta name="twitter:site> element. When absent, the element is not included.
  • additional_head_elements (optional): Additional elements to include in the <head></head> section of the HTML. The elements should be passed using Floki's tuple-based syntax: [{element, attributes, children}].
  • additional_body_elements (optional): Additional elements to include in the <body></body> section of the HTML. The elements should be passed using Floki's tuple-based syntax: [{element, attributes, children}].
  • configuration (optional): The Scalar configuration (e.g. %{ theme: "purple"}). The configuration is set in a <script id="api-reference"/> element as expected by Scalar.

Compile-time configuration 

plug ScalarPlug, path: "/api/docs", spec_path: "/api/spec", title: "API Documentation"

MFA runtime configuration 

plug ScalarPlug, {ConfigurationModule, :scalar_config}

Function runtime configuration 

plug ScalarPlug, fn -> [path: "/api/docs", spec_path: "/api/spec", title: "API Documentation"] end

Summary

Types

options()

Functions

call(conn, opts)

If the request matches the path configuration value, it returns a HTML response with a Scalar setup to load the API documentation. Otherwise it returns the same connection.

init(opts)

Initializes the plug with the options or a mfa tuple to load the configuration at runtime.

Types

Link to this type

options()

View Source 
@type options() :: [
  path: String.t(),
  spec_href: String.t(),
  title: String.t(),
  og_title: String.t(),
  url: String.t(),
  image_url: String.t(),
  x_handle: String.t(),
  configuration: map(),
  additional_head_elements: tuple(),
  additional_body_elements: tuple()
]

Functions

Link to this function

call(conn, opts)

View Source 
@spec call(Plug.Conn.t(), options() | mfa() | (... -> any())) :: Plug.Conn.t()

If the request matches the path configuration value, it returns a HTML response with a Scalar setup to load the API documentation. Otherwise it returns the same connection.

Link to this function

init(opts)

View Source 
@spec init(opts :: options() | mfa()) :: any()

Initializes the plug with the options or a mfa tuple to load the configuration at runtime.