Rolodex v0.6.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 setupauth_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 schemasfile_name
(default: "api.json") - The name of the output file with the processed documentationfilters
(default::none
) - A list of maps or functions used to filter out routes from your documentation. Filters are matched againstRolodex.Route
structs inRolodex.Route.matches_filter?/2
.locale
(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
.processor
(default:Rolodex.Processors.Swagger
) - Module implementing theRolodex.Processor
behaviourserver_urls
(default: []) - List of base url(s) for your API pathswriter
(default:Rolodex.Writers.FileWriter
) - Module implementing theRolodex.Writer
behaviour to be used to write out the docs
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",
file_name: "api.json",
filters: :none,
locale: "en",
processor: MyProcessor,
server_urls: ["https://myapp.io"],
router: MyRouter
]
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(),
file_name: binary(),
filters: [map() | (Rolodex.Route.t() -> boolean())] | :none,
locale: binary(),
pipelines: pipeline_configs() | nil,
processor: module(),
router: module(),
server_urls: [binary()],
title: binary(),
version: binary(),
writer: module()
}
t() :: %Rolodex.Config{ auth: map(), default_content_type: binary(), description: binary(), file_name: binary(), filters: [map() | (Rolodex.Route.t() -> boolean())] | :none, locale: binary(), pipelines: pipeline_configs() | nil, processor: module(), router: module(), server_urls: [binary()], title: binary(), version: binary(), writer: module() }
Link to this section Functions
Link to this function
new(module)
Link to this function
set_auth_config(opts, module)
Link to this section Callbacks
Link to this callback
pipelines_spec()
Link to this callback