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"
    sinceApiVersion="1.0"
    defaultApiVersion="1.1"
    latestApiVersion="1.2"
    bootstrap="vendor/autoload.php"
>
    <controllers>
        <filter>
            <directory name="src/Controllers/" suffix=".php" />
        </filter>
    </controllers>

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

            <class name="\My\Application\Representations\Representation" noMethod="true" />

            <exclude>
                <class name="\My\Application\Representations\Error" />
                <class name="\My\Application\Representations\CodedError" />
            </exclude>
        </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
sinceApiVersion	🚫	This is the first version of your API. eg: "1.0"
defaultApiVersion	✅	If you happen to have a latest API version that's different than that normal developers of your API get, this is your "default" API version. So if your latest is "1.2", but normal users are on "1.1", this would be "1.1".
latestApiVersion	✅	The absolute latest version of your API.
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

<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.
  • Add in a method attribute.
    • If the representation doesn't have a method, or documentation, you can specify noMethod="true".
• Add in an <excludes> block, with <class> 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>

<scopes>

<parameterTokens>

<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