defmodule Apical do
@moduledoc """
Generates a web router from an OpenAPI document.
Building an OpenAPI-compliant Phoenix router can be as simple as:
```elixir
defmodule MyRouter do
require Apical
Apical.router_from_file(
"path/to/openapi.yaml",
controller: MyProjectWeb.ApiController
)
end
```
See https://spec.openapis.org/oas/v3.1.0 for details on how to compose an OpenAPI
schema.
Using the macros `router_from_string/2` or `router_from_file/2` you may generate a
`Phoenix.Router` or an `Apical.Plug.Router` (for `Plug`-only deployments) that
corresponds to OpenAPI document.
> ### Tip {: .tip }
>
> In general, using `router_from_file/2` is should be preferred, especially if you
> must maintain multiple versions of the schema, though you may find it easier to
> iterate using `router_from_string/2` during early development. In that case, it
> is possible to switch to `router_from_file/2` when you are ready to finalize your
> API design or start versioning
The following activities are performed by the router generated by the macros:
- Tagging inbound requests with API version
- Constructing route and http verb matches in the router
- Parameter operations
- Supports:
- Cookie parameters
- Header parameters
- Path parameters
- Query parameters
- Features:
- Style decoding based on parameter styles (see https://spec.openapis.org/oas/v3.1.0#style-values)
- Custom style decoding
- Parameter marshalling (converting strings to types)
- Parameter validation
- Request body validation
- content-length and content-type validation
- matching content-type with request body plugs
- Automatic json and `form-encoded` request body parsing
- Parameter marshalling for `form-encoded` requests
### Options
The following options are common to `router_from_string/2` and `router_from_file/2`.
#### Global options
- `for`: allows you to select which framework you would like to generate the router
for. Select one of:
- `Phoenix`: (default) generates the interior code for a `Phoenix.Router` module
- `Plug`: generates the interior code for an `Apical.Plug.Router` module.
> #### Warning {: .warning }
>
> The `Apical.Plug.Router` module does not have the same interface as
> `Plug.Router`, though it is a plug.
- `encoding`: mimetype which describes how the schema is encoded.
required in `router_from_string/2`, deduced from filename in `router_from_file/2`.
- `decoders`: A proplist of mimetype to decoders.
If you use an encoding that isn't `application/json` or `application/yaml` you
should provide this proplist, which, at a minimum, contains
`[{encoding_mimetype, {module, function}}]`. The call `module.function(string)`
should return a map representing the OpenAPI schema, and should raise in the
case that the content is not decodable.
- `root`: the root path for the router.
Defaults to `/v{major}` where `major` is the major version of the API, as declared
under `info.version` in the schema.
- `testing`: lets you generate additional modules to assist with testing. This
is a keyword list with the following sub-options:
- `behaviour`: builds a behaviour module with the behaviour name that has
callbacks that match the `operationId`s in the schema. Defaults to
`<router>.Api`. If `false`, skips this step.
- `controller`: builds a controller module with the controller name that
has functions that match the `operationId`s in the schema. This controller
will delegate its functions to the mock module. Defaults to
`<router>.Controller`. If `false`, skips this step.
- `mock`: builds a mock module using `Mox` that mocks the behaviour.
Defaults to `<router>.Mock`. If `false`, skips this step.
- `bypass`: if true, generates a `bypass/1` function that sets up `Bypass`
for use in tests. Defaults to `false`. Can not be `true` if any of the
above options are set to `false`.
you may also pass `:auto` to `testing` to set everything up automatically.
- `dump`: (For debugging), sends formatted code of the router to stdout.
Defaults to `false`. If set to `:all`, will also pass `dump: true` to Exonerate.
#### Scopable options
The following options are *scopable*. They may be placed as top-level options
or under the scopes (see below)
- `controller`: Plug module which contains code implementing the API.
It is recommended to `use Phoenix.Controller` in this plug module, or the
functions may or may not be targeted as expected.
Controller modules should implement public functions corresponding to the
`operationId` of each operation in the schema. These functions must be
cased in the same fashion as the `operationId`, and like all Phoenix Controller
functions, take two arguments:
- `conn`: the `Plug.Conn` for the request
- `params`: a map containing the parameters for the operation. This is
identical to `conn.params`.
> ### Important {: .warning }
>
> Unlike standard Phoenix controller functions, parameters declared in the
> `parameters` list of the operation are made available in the `params`
> argument as well as in `conn.params`. These parameters will overwrite
> any fields present in body parameters that happen to have the same name.
A single router may have its routes target more than one controller.
- `extra_plugs`: a list of plugs to execute after the route has matched
but before the parameter and body pipeline has been executed.
These plugs are defined using `{atom, [args...]}` where `args` is
a list of plug options to be applied to the plug, or `atom` which
is equivalent to `{atom, []}`. These may be either a function plug
or a module plug.
> ### Route-level Security Plugs {: .tip }
>
> Route-level security checks should be performed in plugs declared in
> `extra_plugs`, until `Apical` provides direct support for security
> schemes.
> ### Global plugs {: .tip }
>
> if you need plugs to be executed for all routes, declare those plugs
> in the router module before the macro `Exonerate.router_from_*`.
> ### Post-pipeline plugs {: .tip }
>
> if you need plugs to be executed after the parameter and body pipeline,
> for example, for row-level security checks, declare those plugs in the
> controller module. Note that these plugs should be able to match on
> the `operationId` atom using `conn.private.operation_id`.
- `styles`: a proplist of custom styles and their corresponding parsers.
Each parser is represented as `{module, function, [args...]}` or
`{module, function}` which is equivalent too `{module, function []}`.
The parsers are functions that are called as
`module.function(string, args...)`, and return `{:ok, value}` or
`{:error, message}`. The message should be a string describing the
error.
The following styles are supported by default and do not need to be
included in the styles proplist:
- `"matrix"`
- `"label"`
- `"simple"`
- `"form"`
- `"space_delimited"`
- `"pipe_delimited"`
- `"deep_object"`
see https://spec.openapis.org/oas/v3.1.0#style-values for description
of these styles.
> ### Custom styles {: .warning }
>
> If you need to support a custom style, you *must* add it to the
> `styles` proplist.
> ### Form-exploded objects {: .error }
>
> Form-exploded style parameters with type `object` in their schema are
> not supported due to ambiguity in their definition per the OpenAPI
> specification.
- `content_sources`: A proplist of media-types (as **string** keys) and
functions to act as the source for request body. These should be
defined as `{media_type, {module, [opts...]}}`. These opts will be
passed into the `c:Apical.Plugs.RequestBody.Source.fetch/3`.
- `nest_all_json`: Analogous to the option in `Plug.Parsers.JSON`, this
option will nest all json request body payloads under the `"_json"` key.
if this is not true, objects payloads will be merged into `conn.params`.
#### Available scopes
The scopes have the following precedence:
operation_ids > groups > tags > parameters > global
- `operation_ids`: A keywordlist of `operationId`s (as atom keys) and options
to target to these operations.
The keys must be cased in the same fashion as the `operationId` in the
schema.
- `tags`: A keywordlist of tags (as atom keys) and options to target to those
tags.
The tag keys must be cased in the same fashion as their tags in the schema.
- `parameters`: A keywordlist of parameters (as atom keys) and options to
target to those parameters.
The parameter keys must be cased in the same fashion (including kebab-case)
Note that this scope may be further nested inside of `tag` and
`operation_ids` scopes.
- `groups`: A keywordlist of groups (as atom keys) and options to target to
those groups. The group definition should start off with the names of the
operationIds that are in the group (as atoms), followed by the options to
send to them (as keyword lists)
#### Scoped options
The following options are only valid in a single scope:
- `alias`: (scoped to `:operation_ids`) overrides the name of the function
pointed to by the `operationId` in the schema.
- `marshal`: (scoped to `parameters`) overrides the marshaller to use for
parameter. May be one of:
- `false`: to disable default marshalling and do nothing. Also disables
validation of the parameter.
- `atom`: to call a local function,
- `{atom, list}`: to call a local function with extra parameters,
- `{module, atom}`: to call a remote function
- `{module, atom, list}`: to call a remote function with extra parameters.
Note that the local function must be an exported function.
The called function must return `{:ok, value}` to marshal the string and
substitute the value as the parameter, or `{:error, String.t}` to return
a 400 error with the reason as described.
- `validate`: (scoped to `parameters`, boolean, defaults to `true`) if sets
to false, disables validation of the parameter. Note if `marshal: false`
is set, validation will automatically be disabled.
"""
alias Apical.Router
alias Apical.Tools
@spec router_from_string(String.t(), Keyword.t()) :: any()
@doc """
Generates a web router from a String containing an OpenAPI document.
### Example:
```elixir
defmodule MyRouter do
require Apical
Apical.router_from_string(
\"""
openapi: 3.1.0
info:
title: My API
version: 1.0.0
paths:
"/":
get:
operationId: getOperation
responses:
"200":
description: OK
\""",
controller: MyProjectWeb.ApiController,
encoding: "application/yaml"
)
end
```
For options see `Apical` module docs.
"""
defmacro router_from_string(string, opts) do
opts =
opts
|> Macro.expand_literals(__CALLER__)
|> Keyword.put(:router, __CALLER__.module)
router(string, opts)
end
@spec router_from_file(Path.t(), Keyword.t()) :: any()
@doc """
Generates a web router from a String containing an OpenAPI document.
### Example:
```elixir
defmodule MyRouter do
require Apical
Apical.router_from_file(
"path/to/openapi.yaml",
controller: MyProjectWeb.ApiController
)
end
```
For options see `Apical` module docs.
"""
defmacro router_from_file(file, opts) do
opts =
opts
|> Macro.expand_literals(__CALLER__)
|> Keyword.merge(file: file)
|> Keyword.put_new_lazy(:encoding, fn -> find_encoding(file, opts) end)
|> Keyword.put(:router, __CALLER__.module)
file
|> Macro.expand(__CALLER__)
|> File.read!()
|> router(opts)
end
defp router(string, opts) do
string
|> Tools.decode(opts)
|> Router.build(string, opts)
|> Tools.maybe_dump(opts)
end
defp find_encoding(filename, _opts) do
case Path.extname(filename) do
".json" -> "application/json"
".yaml" -> "application/yaml"
_ -> raise "unsupported file extension"
end
end
end
