Mix Apidoc Task
A mix task that triggers apidoc to create documentation for RESTful web APIs.
Usage
- Configure apidoc in your
mix.exs
:
def project do
[app: :your_app,
apidoc: apidoc(Mix.env)
# Add `:apidoc` to your compilers if you want it to run upon `mix compile`
compilers: [:apidoc] ++ Mix.compilers,
deps: deps
...]
end
# It makes sense to have an apidoc config per mix environment as URLs will
# most likely differ between your environments.
defp apidoc(:dev) do
# Omit `sampleUrl` if you don't want to have sample requests in the
# documentation.
[url: "http://localhost:4000/api",
sampleUrl: "http://localhost:4000/api"] ++ apidoc
end
defp apidoc do
# See http://apidocjs.com/#configuration-settings for a full list of
# parameters. Note: Use Elixir terms as values. They will be translated
# to JSON and stored in `_build/dev/apidoc.json`.
[name: "Your API",
version: "1.0.0",
description: "Your API description",
title: "Your API Title"]
end
def deps do
# Add it to your dependencies
[{:mix_apidoc, "~> 0.1"},
...]
end
Create a file called
package.json
in your project directory. If you’re in a Phoenix project, Phoenix creates it for you.Add apidoc as a dependency to your
package.json
{
"repository": {
},
"dependencies": {
"apidoc": ">= 0.14.0"
}
}
Install apidoc using the node package manager:
$ npm install
Task-specific configuration options
By default, the apidoc task will look for apidoc comments in web/controllers
and generate the documentation into priv/static/apidoc
. You may override those
paths in the config:
input_dir: "web",
output_dir: "priv/static/html"
The mix task also assumes that your apidoc binary is
node_modules/apidoc/bin/apidoc
. This is where it installs in step 4. If you
prefer to use your system-wide apidoc installation instead, change the
apidoc_bin
config parameter:
apidoc_bin: "apidoc"
Apart from those mix task specific parameters, you can set all apidoc parameters as described on the apidoc webpage.
Additionally, you can specify additional command line arguments by specifying the following configuration parameter in the config:
extra_args: ["-e", "admin", "-t", "/path/to/custom/template"]
Running the task
If you added the task to the list of compilers, just run
$ mix compile
If not, or if you want to run it separately, run it with
$ mix compile.apidoc