cowboy-swagger
Swagger integration for Cowboy (built on trails).
Contact Us
If you find any bugs or have a problem while using this library, please open an issue in this repo (or a pull request :)).
Why Cowboy Swagger?
Simple, because there isn't a tool in Erlang to document Cowboy RESTful APIs easy and fast, and to improve development productivity.
With cowboy_swagger is possible to integrate Swagger to your Erlang projects that use Cowboy as a web server.
It is extremely easy to use, and with just a few steps you'll have a nice Web documentation for your RESTful APIs.
To learn a bit more about Swagger, please check this blog post.
How to Use it?
This is the best part. It is extremely easy.
1. Document each Cowboy Handler
Because cowboy_swagger runs on top of trails, the first thing that you have to do
is document all about your handler within the trails metadata. Keep in mind that
all fields defined within each method into the metadata must be compliant with the
Swagger specification.
For example, suppose that you have example_echo_handler, so it must implement the
c:trails_handler:trails/0 callback:
trails() ->
Metadata =
#{get =>
#{tags => [~"echo"],
description => ~"Gets echo var from the server",
produces => [~"text/plain"]
},
put =>
#{tags => [~"echo"],
description => ~"Sets echo var in the server",
produces => [~"text/plain"],
parameters => [
#{name => ~"echo",
description => ~"Echo message",
in => ~"path",
required => false,
type => ~"string"}
]
}
},
[trails:trail("/message/[:echo]", example_echo_handler, [], Metadata)].
To get a better idea of how your handler should look like, please check example/src/example_echo_handler.erl.
2. Include cowboy_swagger in your app
First, you need to include cowboy_swagger_handler module in your list of trails to be compiled.
% Include cowboy_swagger_handler in the trails list
Trails = trails:trails([example_echo_handler,
example_description_handler,
cowboy_swagger_handler]),
% store them
trails:store(Trails),
% and then compile them
Dispatch = trails:single_host_compile(Trails),
The snippet of code above is usually placed when you start cowboy. Check it here.
Then add cowboy_swagger to the list of apps to be loaded in your *.app.src file.
{application, example,
[
{description, "Cowboy Swagger Basic Example."},
{vsn, "0.1"},
{applications,
[kernel,
stdlib,
cowboy,
trails,
cowboy_swagger
]},
{modules, []},
{mod, {example, []}},
{registered, []},
{start_phases, [{start_trails_http, []}]}
]
}.
And that's it, you got it. Now start your application and then you will have access to the API docs
under the path /api-docs. Supposing that you're running the app on localhost:8080,
that will be http://localhost:8080/api-docs.
Configuration
Additionally, cowboy_swagger can be configured/customized from a *.config file:
app.config
[
%% Other apps ...
%% cowboy_swagger config
{cowboy_swagger,
[
%% `base_path`: Path where you can access Swagger-UI. Default: `/api-docs`
{base_path, "/api-docs"},
%% `robots_noindex`: Add a robots meta tag to the UI HTML. Default: false.
%% When true, requests noindex, nofollow from search engines.
{robots_noindex, false},
%% Validate path bindings against documented path parameters. Default: false.
{validate_path_parameters, false},
%% `swagger_json_url`: URL loaded by Swagger-UI. Defaults to
%% `base_path` followed by `/swagger.json`. May also be an absolute URL.
%% Only changes the UI source; the local JSON route stays under `base_path`.
{swagger_json_url, "/api-docs/swagger.json"},
%% `json_exporter`: Optional module implementing
%% cowboy_swagger_json_exporter. No exporter is configured by default.
%% {json_exporter, my_swagger_exporter},
%% `static_files`: Static content directory. This is where Swagger-UI
%% is located. Default: `priv/swagger`.
%% Remember that Swagger-UI is embedded into `cowboy-swagger` project,
%% within `priv/swagger` folder. BUT you have to reference that path,
%% and depending on how you're using `cowboy-swagger` it will be different.
%% For example, assuming that you want to run your app which has
%% `cowboy-swagger` as dependency from the console, `static_files` will be:
{static_files, "./deps/cowboy_swagger/priv/swagger"},
%% Custom static_files directories must include swagger-initializer.template
%% with the __SWAGGER_JSON_URL__ placeholder (a complete JavaScript value).
%% `global_spec`: Global fields for Swagger specification.
%% If these fields are not set, `cowboy_swagger` will set default values.
{global_spec,
#{swagger => ~"2.0",
info => #{~"title" => ~"Example API"},
basePath => ~"/api-docs"
}
},
%% `server_spec`:Fields for Swagger specification for a given server.
%% If these fields are not set for a given server, `cowboy_swagger` will use
%% `global_spec` for that server.
{server_spec,
#{my_server =>
#{swagger => ~"2.0",
info => #{~"title" => ~"Example API"},
basePath => ~"/api-docs"
},
my_other_server =>
#{openapi => ~"3.0.0",
info => #{~"title" => ~"Other API"},
basePath => ~"/api-docs"
}
}
}
]
}
].
Validating path parameters
To check that every generated path binding has a matching path parameter in
each visible HTTP operation, enable validate_path_parameters in your
application's sys.config (or the app.config loaded by your application):
[
{cowboy_swagger, [
{validate_path_parameters, true}
]}
].
The default is false, preserving existing generation behavior. When enabled,
a Cowboy route such as /shops/:shop_id/items/:sku requires parameters named
shop_id and sku with in => path. Names are case-sensitive and apply to
any binding name, not just id. Parameters can be declared at the path level,
in each operation, or a combination of both. The existing operation parameter
default of in => path when in is omitted is preserved.
For example, this Erlang handler metadata describes both bindings:
Metadata = #{
parameters => [
#{name => ~"shop_id", in => path, required => true,
schema => #{type => string}}
],
get => #{
parameters => [
#{name => ~"sku", in => path, required => true,
schema => #{type => string}}
],
responses => #{~"200" => #{description => ~"Item found"}}
}
},
Trail = trails:trail("/shops/:shop_id/items/:sku", my_handler, [], Metadata).
A missing parameter, a different name, or an identically named query/header
parameter causes generation to raise an error identifying the generated path,
HTTP method and missing names. For example, /places/:id with only a parameter
named key raises:
{missing_path_parameters, ~"/places/{id}", ~"get", [~"id"]}
Local parameter $ref references are supported, including Swagger 2
#/parameters/... and OpenAPI 3 #/components/parameters/.... JSON Pointer
escaping and percent-encoded fragment tokens are handled. Broken, circular or
external parameter references raise
{unresolved_path_parameter_reference, Path, Method, Reference} if the missing
bindings cannot otherwise be satisfied. External references are not fetched.
An unrelated unresolved reference does not prevent validation when all
bindings already have matching path parameters.
Validation runs in cowboy_swagger:to_json/1,2 before JSON is serialized or
passed to an exporter, using the selected global or server-specific spec.
Invalid documentation therefore fails build-time generation when enabled,
and an HTTP request that generates it returns a server error. Fix the metadata
before enabling the setting in an existing deployment. The setting is read
on each generation and does not change Cowboy route matching.
Optional bindings are checked as they appear in the generated path:
/users/[:slug] currently becomes /users/{slug} and requires a slug
parameter. This option does not expand optional routes into multiple paths.
Hidden operations are skipped; paths without named bindings require no
additional checks. Validation checks the operation entries supplied by the
application, including custom methods, rather than a fixed list of method
names. Non-operation path fields and x-* extensions are skipped.
This is a binding-name check, not a complete Swagger/OpenAPI
schema validator: it does not enforce required: true, infer parameter types
or reject extra path parameters.
Validation before starting Cowboy
To reject invalid documentation before compiling routes or opening a listener,
call cowboy_swagger:validate_paths/1 explicitly in your Erlang startup code:
Trails = trails:trails([my_handler, cowboy_swagger_handler]),
ok = cowboy_swagger:validate_paths(Trails),
ok = trails:store(Trails),
Dispatch = trails:single_host_compile(Trails),
{ok, _} = cowboy:start_clear(
my_listener,
#{socket_opts => [{port, 8080}]},
#{env => #{dispatch => Dispatch}}
).
The function returns ok or raises the same validation errors described above.
Calling it explicitly always validates, regardless of validate_path_parameters.
It builds the specification for validation without serializing the final JSON
or invoking json_exporter, so startup validation does not export a file.
Prepare any application settings and shared parameter definitions before
calling it. Invalid metadata interrupts this startup sequence before
trails:single_host_compile/1 and cowboy:start_clear/3 are reached.
For a server-specific specification, use this Erlang call instead:
ok = cowboy_swagger:validate_paths(my_listener, Trails).
The server reference selects server_spec just as it does in to_json/2, with
fallback to global_spec; the listener need not be running. For multiple hosts,
validate each host's trails with the appropriate server reference before
compiling its routes. Keep validate_path_parameters enabled if subsequent
JSON generation should also detect metadata changes after startup.
Exporting generated JSON
Create src/my_swagger_exporter.erl in the consuming application to implement
the cowboy_swagger_json_exporter behaviour:
-module(my_swagger_exporter).
-behaviour(cowboy_swagger_json_exporter).
-export([export/1]).
export(JSON) ->
ok = file:write_file("swagger.json", JSON).
Then select the module in the application's sys.config (or app.config
loaded by your application), using the same application configuration format
as the app.config example above:
[
%% Other apps ...
%% cowboy_swagger config
{cowboy_swagger,
[
{json_exporter, my_swagger_exporter}
]
}
].
No exporter is configured by default. When enabled, the callback receives the
serialized JSON binary synchronously, once per successful generation through
cowboy_swagger:to_json/1 or to_json/2. The functions still return that same
binary. This includes generation triggered by HTTP requests to swagger.json;
the setting does not mean “export once” or “export only during builds”.
The callback must return ok on success and raise an exception on failure.
Exceptions propagate unchanged with their original stacktrace. The library
checks the callback result with ok = Module:export(JSON); an unexpected return
value fails with a bad match. An invalid exporter module or callback also
fails generation. Exporters choose
their storage destination and must handle concurrent requests or different
server specifications as needed. Do not call to_json from export/1, as that
would recursively invoke the exporter.
Generating swagger.json during a build
Configuring an exporter does not initiate generation. A consuming application
can opt into a post-compile hook that loads its compiled handlers and settings,
collects the trails and calls cowboy_swagger:to_json/1. The library does not
install a build hook automatically.
The example application provides a complete implementation:
cd example
rebar3 as swagger compile
This writes example/_build/swagger/swagger.json without starting the example
application or an HTTP listener. The following build configuration belongs in
example/rebar.config; merge it into the existing profiles entry if present:
{profiles, [
{swagger, [
{post_hooks, [
{compile,
"escript export_swagger.escript _build/swagger config/sys.config "
"_build/swagger/swagger.json"}
]}
]}
]}.
The script adds the selected build's dependency and checkout beam directories to the code path, loads the supplied configuration and invokes generation. It selects the example exporter only inside its own Erlang VM, leaving the application's normal runtime configuration unchanged. Export errors cause the script and the build hook to fail.
For another application, adapt the handler list, exporter and build/configuration paths. The example script accepts a plain Erlang configuration file containing one list of application settings. Resolve configuration includes, environment substitutions or release-specific configuration before invoking it. Definitions or settings normally registered at application startup must also be prepared explicitly by the build script. Handlers must expose their trails without requiring a running application.
Export paths and releases
_build/swagger/swagger.json is the example's build artifact location, not a
path required by the library. Both the build directory and output filename
are explicit script arguments. Relative paths are resolved from the script's
working directory (example when using the example's hook). If you customize
the rebar3 build directory or use another profile, update the hook arguments
to match; the script does not discover those paths automatically.
Building a release does not relocate this artifact or include it automatically.
The example's plain rebar3 release does not enable the swagger profile.
To package the generated file, run the export before assembling the release
and explicitly copy it with a relx overlay, or generate it into the consuming
application's priv directory before packaging. See the
release example.
The example enables its exporter only in the build script's VM. If you also
configure an exporter in a running release, relative output paths resolve
from that process's working directory, which may differ from the project
directory. For runtime writes, configure an explicit writable destination.
For reading a specification packaged in an application's priv directory,
resolve its installed location with
filename:join(code:priv_dir(my_app), "swagger.json"); the installed application
directory is not necessarily writable.
Preventing Swagger UI indexing
To request that search engines exclude the documentation page from their index
and do not follow its links, enable robots_noindex in your application's
sys.config (or the app.config loaded by your application):
[
%% Other apps ...
%% cowboy_swagger config
{cowboy_swagger,
[
{base_path, "/v2/docs"},
{robots_noindex, true}
]
}
].
The HTML returned by /v2/docs/index.html will contain the following tag
inside <head>:
<meta name="robots" content="noindex, nofollow" />
The setting defaults to false, which returns the original HTML unchanged.
It is read for each HTML request, so it can also be changed with
application:set_env(cowboy_swagger, robots_noindex, true) without restarting
the listener. Refresh the page to fetch the updated HTML.
Custom static_files directories are supported: the handler reads their
index.html and inserts the tag before the first closing </head> tag
(case-insensitive). The file on disk is never modified. HTML without a closing
head tag is returned unchanged. Custom pages should omit an existing robots
meta tag when using this setting, to avoid conflicting directives.
This setting affects the UI HTML page only. It does not add directives to the JSON specification or restrict access to the documentation. Use authentication or network restrictions when access must be limited.
Diferences between global_spec and server_spec
global_spec is a single config which contains every specification for your application.
server_spec is a config map with servers as key and a specification (just like global_spec) as a
value.
Since global_spec contains all of the definitions it can create a really messy swagger if your
application starts multiple servers. With server_spec everything is separated so your swagger will
stay clean and relevant for a given server.
Note: A server can use either global_spec or server_spec it cannot be hybrid so you have to make
a choice.
Definitions
Definitions can be used for describing parameters, responses and security schemas.
For adding definitions to your app, you have 2 choices:
- Add a
definitionskey to your cowboy_swaggerglobal_specorserver_specmap. - Add them by calling
cowboy_swagger:add_definition/2orcowboy_swagger:add_definition_to_server/3.
Let's say you want to describe a POST call to a newspapers endpoint that requires
name and description fields only, you can do it like this:
Option 1:
With global_spec
[ ... % other configurations
, { cowboy_swagger
, [ { global_spec
, #{ swagger => ~"2.0"
, info => #{~"title" => ~"My app API"}
, definitions => #{
~"RequestBody" =>
#{ name =>
#{ type => ~"string"
, description => ~"Newspaper name"
}
, description =>
#{ type => ~"string"
, description => ~"Newspaper description"
}
}
}
}
}
]
}
]
With server_spec
[ ... % other configurations
, { cowboy_swagger
, [ { server_spec
, #{server =>
#{ swagger => ~"2.0"
, info => #{~"title" => ~"My app API"}
, definitions => #{
~"RequestBody" =>
#{ name =>
#{ type => ~"string"
, description => ~"Newspaper name"
}
, description =>
#{ type => ~"string"
, description => ~"Newspaper description"
}
}
}
}
}
}
]
}
]
Option 2:
For the second choice, you can do it for example in one or several start_phases,
directly in your handler or any other place you want.
-spec trails() -> trails:trails().
trails() ->
DefinitionName = ~"RequestBody",
DefinitionProperties =
#{ ~"name" =>
#{ type => ~"string"
, description => ~"Newspaper name"
}
, ~"description" =>
#{ type => ~"string"
, description => ~"Newspaper description"
}
},
% Add the definition
ok = cowboy_swagger:add_definition(DefinitionName, DefinitionProperties),
...
-spec trails() -> trails:trails().
trails() ->
Server = my_ranch_listener,
DefinitionName = ~"RequestBody",
DefinitionProperties =
#{ ~"name" =>
#{ type => ~"string"
, description => ~"Newspaper name"
}
, ~"description" =>
#{ type => ~"string"
, description => ~"Newspaper description"
}
},
% Add the definition
ok = cowboy_swagger:add_definition_to_server(Server, DefinitionName, DefinitionProperties),
...
Now in your handler's trails callback function you can use it:
...
RequestBody =
#{ name => ~"request body"
, in => body
, description => ~"request body (as json)"
, required => true
% Use the previously created `RequestBody' definition
, schema => cowboy_swagger:schema(~"RequestBody")
},
Metadata =
#{ get =>
#{ tags => [~"newspapers"]
, description => ~"Returns the list of newspapers"
, produces => [~"application/json"]
}
, post =>
# { tags => [~"newspapers"]
, description => ~"Creates a new newspaper"
, consumes => [~"application/json"]
, produces => [~"application/json"]
, parameters => [RequestBody] % and then use that parameter here
}
},
Path = "/newspapers",
Options = #{path => Path},
[trails:trail(Path, newspapers_handler, Options, Metadata)].
What this does for you is add a nice response, parameter or security
model in swagger-ui, so client developers will know exactly what parameters
the API expects for every endpoint.
Example
See the Erlang example for a working Cowboy application with public endpoints, path parameters and Bearer authorization through Swagger UI.