Configuration

In order to instruct Mill on where to look for documentation, and any constraints you may have, Mill requires the use of an XML configuration file (mill.xml).

<?xml version="1.0" encoding="UTF-8"?>
<mill
    name="Movie showtimes API"
    bootstrap="vendor/autoload.php"
>
    <versions>
        <version name="1.0" />
        <version name="1.1" default="true" />
        <version name="1.2" />
    </versions>

    <controllers>
        <filter>
            <directory name="src/Controllers/" suffix=".php" />
        </filter>
    </controllers>

    <representations>
        <filter>
            <directory name="src/Representations/" method="create" suffix=".php"  />

            <excludes>
                <exclude name="\My\Application\Representations\Error" />
                <exclude name="\My\Application\Representations\CodedError" />
                <exclude name="\My\Application\Representations\Representation" />
            </excludes>
        </filter>

        <errors>
            <class name="\My\Application\Representations\Error" needsErrorCode="false" />
            <class name="\My\Application\Representations\CodedError" needsErrorCode="true" />
        </errors>
    </representations>
</mill>

Options

Option	Optional	Description
bootstrap	🚫	Relative path to a PHP bootstrap file that will get loaded before Mill does any work. This is usually a Composer vendor/autoload.php file. This is necessary so Mill can access, and parse your API classes for documentation.

Parameters

<versions>

The <versions> param lets you inform Mill on the various version of your API that exist. From here, Mill will then know what versions to compile documentation for.

To set a "default" API version, use the default="true" attribute. You must have a default version set, and there can only be one.

<controllers>

The <controllers> parameter lets you inform Mill on where your API controllers live. You can:

• Use <directory> elements to specify a directory name (and suffix).
• Specify a <class> element for a specific, fully-qualified class name.
• Add in an <excludes> block, with <class> elements for excluding specific controllers from being parsed.

<representations>

The <representations> parameter lets you inform Mill on where your API data representations (the content that your controllers` return, live. You can:

• Use <directory> elements to specify a directory name (and suffix).
  • Add in a method attribute so Mill knows the method to pull representation documentation from.
• Specify a <class> element for a specific, fully-qualified class name, and add a method attribute.
  • If the representation doesn't have a method, or documentation, you should add it to the excludes block.
• Add in an <excludes> block, with <name> elements for excluding specific controllers from being parsed.

<errors>

The representation <errors> parameter lets you tell Mill where your error representations are (the content that is returned from @api-throws annotations. Here you can specify a <class> with a a fully-qualified class name.

A required attribute for the <class> element here, is needsErrorCode, which tells Mill if your error representation handles, and returns, a unique error code. The way that looks in your documentation is:

/**
 * …
 *
 * @api-throws:public {403} \ErrorRepresentation (\AppError::USER_NOT_ALLOWED) 
 *     If the user isn't allowed to do something.
 */
public function PATCH()
{
    …
}

Here, \ErrorRepresentation would have needsErrorCode="true".

<capabilities>

If your API has a capability-backed permission system for granting certain endpoints, or data in representations, to specific users, you should use this to document that.

<capabilities>
    <capability name="BUY_TICKETS" />
    <capability name="MOVIE_RATINGS" />
    <capability name="NONE" />
</capabilities>

You can find usage details for capabilities in the @api-capability, @api-param, @api-return, and @api-throws documentation.

<scopes>

If your API has an authentication system that requires a specific scope(s) for using an API endpoint, use this to document those.

Example:

<scopes>
    <scope name="create" />
    <scope name="delete" />
    <scope name="edit" />
    <scope name="public" />
</scopes>

You can find usage details for scopes in the @api-scope documentation.

<parameterTokens>

Parameter tokens allow you to create a @api-param shortcode to save time for common elements in your API (like paging or sorting).

Example:

<parameterTokens>
    <token name="page">{int} page (optional) The page number to show.</token>
    <token name="per_page">{int} per_page (optional) Number of items to show on each page. Max 100.</token>
    <token name="filter">{string} filter (optional) Filter to apply to the results.</token>
</parameterTokens>

You can find usage details for parameter tokens in the @api-param documentation.

<uriSegments>

<translations>

The uriSegment translations section allows you to set up translation elements for @api-uriSegment annotations. Say, in your code, the route for a video is at /videos/+video_id, but in your documentation, you want it to just say /videos/+id, this is the place todo that.

Example:

<uriSegments>
    <translations>
        <translation from="id" to="video_id" />
    </translations>
</uriSegments>

Notes

• For all directory paths, they should be relative to the location of your mill.xml configuration file.
• If you specify a controller, representation, capability, or scope in your documentation that hasn't been configured here, API documentation generation will fail with errors.

XSD

If you wish to use it for a reference, Mill has an included XML schema definition