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 setuprender_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 inRolodex.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. SeeRolodex.PipelineConfig
for details about valid options and defaults
For spec/0
, the following are valid options:
description
(required) - Description for your documentation outputrouter
(required) -Phoenix.Router
module to inspecttitle
(required) - Title for your documentation outputversion
(required) - Your documentation's versiondefault_content_type
(default: "application/json") - Default content type used for request body and response schemaslocale
(default:"en"
) - Locale key to use when processing descriptionspipelines
(default:%{}
) - Map of pipeline configs. Used to set default parameter values for all routes in a pipeline. SeeRolodex.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()
pipeline_configs() :: %{optional(:atom) => Rolodex.PipelineConfig.t()}
pipeline_configs() :: %{optional(:atom) => Rolodex.PipelineConfig.t()}
Link to this type
t()
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()
}
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)
Link to this section Callbacks
Link to this callback
auth_spec()
Link to this callback
pipelines_spec()
Link to this callback
render_groups_spec()
render_groups_spec()
render_groups_spec() :: list()
render_groups_spec() :: list()
Link to this callback