# Mix Apidoc Task
A mix task that triggers [apidoc](http://apidocjs.com "apidoc") to create
documentation for RESTful web APIs.
## Usage
1. Configure apidoc in your `mix.exs`:
```elixir
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
# Do not generate apidoc documentation for `test` environment
defp apidoc(env) when env not in [:dev, :prod], do: []
defp apidoc(env) do
base_url = case env do
:dev -> "http://localhost:4000"
:prod -> "https://prod-host"
end
# 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`.
#
# Omit `sampleUrl` if you don't want to have sample requests in the
# documentation.
[url: "#{base_url}/api",
sampleUrl: "#{base_url}/api",
name: "Your API",
version: "1.0.0",
description: "Your API description",
title: "Your API Title"]
# You may also provide a list of nested configs in order to generate
# multiple documentations. When doing so, you need to specify a
# dedicated `output_dir` for each. Example:
#
#[[input_dir: Path.join(~w"lib myapp_web controllers public"),
# output_dir: Path.join(~w"priv static apidoc public"),
# url: "#{base_url}/public/api",
# sampleUrl: "#{base_url}/api",
# name: "Your Public API",
# version: "1.0.0",
# description: "Your public API description",
# title: "Your Public API"],
# [input_dir: Path.join(~w"lib myapp_web controllers private"),
# output_dir: Path.join(~w"priv static apidoc private"),
# url: "#{base_url}/private/api",
# sampleUrl: "#{base_url}/api",
# name: "Your Private API",
# version: "1.0.0",
# description: "Your private API description",
# title: "Your Private API"]]
end
def deps do
# Add it to your dependencies
[{:mix_apidoc, "~> 0.5.1"},
...]
end
```
2. Create a file called `package.json` or use the one generated by Phoenix
(located in the `assets` directory since Phoenix 1.3).
3. Add apidoc as a dependency to your `package.json`
```json
{
"repository": {},
"dependencies": {
"apidoc": ">= 0.17.6"
}
}
```
4. Install apidoc using the node package manager:
```sh
$ cd assets
$ npm install
```
5. Add apidoc comments to your controllers:
```elixir
@apidoc """
@api {get} /user/:id Request User information
@apiName GetUser
@apiGroup User
@apiParam {Number} id Users unique ID.
@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname Lastname of the User.
"""
```
## Task-specific configuration options
By default, the apidoc task will look for apidoc comments in the `controllers`
directory created by Phoenix and generate the documentation into
`priv/static/apidoc`. You may override those paths in the config:
```elixir
input_dir: "web",
output_dir: "priv/static/html"
```
The mix task also assumes that your apidoc binary is
`node_modules/apidoc/bin/apidoc` or `assets/node_modules/apidoc/bin/apidoc` in a
Phoenix 1.3 project. 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:
```elixir
apidoc_bin: "apidoc"
```
Apart from those mix task specific parameters, you can set all apidoc parameters
as described on the [apidoc](http://apidocjs.com/#configuration)
webpage.
Additionally, you can specify additional command line arguments by specifying
the following configuration parameter in the config:
```elixir
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`
