Rolodex v0.7.1 Rolodex.Config behaviour

A behaviour for defining Rolodex config and functions to parse config.

To define your config for Rolodex, use Rolodex.Config in a module and override the default behaviour functions. Then, tell Rolodex the name of your config module in your project's configuration files.

# Your config definition
defmodule MyRolodexConfig do
  use Rolodex.Config

  def spec() do
    [
      title: "My API",
      description: "My API's description",
      version: "1.0.0"
    ]
  end
end

# In `config.exs`
config :rolodex, module: MyRolodexConfig

Usage

Your Rolodex config module exports three functions, which each return an empty list by default:

  • spec/0 - Basic configuration for your Rolodex setup
  • render_groups_spec/0 - Definitions for render targets for your API docs. A render group is combination of: (optional) route filters, a processor, a writer, and options for the writer. You can specify more than one render group to create multiple docs outputs for your API. By default, one render group will be defined using the default values in Rolodex.RenderGroupConfig.
  • auth_spec/0 - Definitions for shared auth patterns to be used in routes. Auth definitions should follow the OpenAPI pattern, but keys can use snake_case and will be converted to camelCase for the OpenAPI target.
  • pipelines_config/0 - Sets any shared defaults for your Phoenix Router pipelines. See Rolodex.PipelineConfig for details about valid options and defaults

For spec/0, the following are valid options:

  • description (required) - Description for your documentation output
  • router (required) - Phoenix.Router module to inspect
  • title (required) - Title for your documentation output
  • version (required) - Your documentation's version
  • default_content_type (default: "application/json") - Default content type used for request body and response schemas
  • locale (default: "en") - Locale key to use when processing descriptions
  • pipelines (default: %{}) - Map of pipeline configs. Used to set default parameter values for all routes in a pipeline. See Rolodex.PipelineConfig.
  • render_groups (default: Rolodex.RenderGroupConfig) - List of render groups.
  • server_urls (default: []) - List of base url(s) for your API paths

Full Example

defmodule MyRolodexConfig do
  use Rolodex.Config

  def spec() do
    [
      title: "My API",
      description: "My API's description",
      version: "1.0.0",
      default_content_type: "application/json+api",
      locale: "en",
      server_urls: ["https://myapp.io"],
      router: MyRouter
    ]
  end

  def render_groups_spec() do
    [
      [writer_opts: [file_name: "api-public.json"]],
      [writer_opts: [file_name: "api-private.json"]]
    ]
  end

  def auth_spec() do
    [
      BearerAuth: [
        type: "http",
        scheme: "bearer"
      ],
      OAuth: [
        type: "oauth2",
        flows: [
          authorization_code: [
            authorization_url: "https://example.io/oauth2/authorize",
            token_url: "https://example.io/oauth2/token",
            scopes: [
              "user.read",
              "account.read",
              "account.write"
            ]
          ]
        ]
      ]
    ]
  end

  def pipelines_spec() do
    [
      api: [
        headers: ["X-Request-ID": :uuid],
        query_params: [includes: :string]
      ]
    ]
  end
end

Link to this section Summary

Link to this section Types

Link to this type

pipeline_configs()
pipeline_configs() :: %{optional(:atom) => Rolodex.PipelineConfig.t()}

Link to this type

t()
t() :: %Rolodex.Config{
  auth: map(),
  default_content_type: binary(),
  description: binary(),
  locale: binary(),
  pipelines: pipeline_configs() | nil,
  render_groups: [Rolodex.RenderGroupConfig.t()],
  router: module(),
  server_urls: [binary()],
  title: binary(),
  version: binary()
}

Link to this section Functions

Link to this function

new(module)
new(module()) :: t()

Link to this section Callbacks

Link to this callback

auth_spec()
auth_spec() :: keyword() | map()

Link to this callback

pipelines_spec()
pipelines_spec() :: keyword() | map()

Link to this callback

render_groups_spec()
render_groups_spec() :: list()

Link to this callback

spec()
spec() :: keyword() | map()