# 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

    # 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
  ```

  2. Create a file called `package.json` in your project directory.
     If you're in a Phoenix project, Phoenix creates it for you.

  3. Add apidoc as a dependency to your `package.json`

```json
{
  "repository": {
  },
  "dependencies": {
    "apidoc": ">= 0.14.0"
  }
}
```

4. 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:

```elixir
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:

```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 "apidoc/#configuration-settings")
webpage.

## 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`