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: a Rolodex Router, 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. At least one render group specification is required.
• 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
• 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"]
    ]
  end

  def render_groups_spec() do
    [
      [router: MyRouter, writer_opts: [file_name: "api-public.json"]],
      [router: MyRouter, 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