README

This package turns php method doc comments in an API into a backplane.json file for use with mashery/iodocs. It uses annotations to determine how to fill in the details for each API endpoint.

Traps!

Here, I'll list important things you should probably be aware of before using this.

The Doctrine annotation parser does not support empty arrays, so if you use that in a Document you will get parsing exceptions.

Setup

Standalone

Clone the repo, and in your terminal navigate to it. Run php composer.phar install, and you're golden.

Composer dependency

Add backplane/apidoc-generator to your composer.json file, run composer install. Now you can run it from vendor/bin/iodocsgen.

Converting PHPDocs to IODocs

Run the generator as so:

path/to/iodocsgen [--iodocs] path/to/api/ output.json

The --iodocs flag may be omitted - it is assumed.

Valid modifiers

When generating iodocs, these flags are valid:

--bootstrap|b path/to/bootstrap.php: A php file to bootstrap from before generating docs.
--config|c path/to/config.json: A json file containing more parameters.

Running with config

In a config file, you can specify these options:

api: string path to the API to document
output: string path to the file to output to.
bootstrap: string, same as the above bootstrap modifier.
bootstrap_args: object, Hash of arguments to pass to the bootstrap, which are accessible in the bootstrap file through the $params array.
exclude: array of paths to ignore inside the API directory
dependencies: array of paths to include, but not consider for documentation (so long as they are outside of the api path)

If you use the api and output flags, you can omit those arguments when invoking the tool.

Example JSON configuration

{
  "api": "/path/to/api",
  "output": "/path/to/output/file",
  "exclude": [
    "file/to/exclude.php",
    "directory/to/exclude",
    "another/directory/to/exclude/",
  ],
  "bootstrap": /path/to/bootstrap.php,
  "dependencies": [
    "/path/to/dependency.php"
  ]
}

Relative paths

All paths in exclude and dependencies are relative to the API location.
When bootstrap is specified as a command line flag, it is relative to the current working directory. When specified in config, it is relative to the config file's location.

Argument vs config precedence

api and output are required, either both set in your config file or both provided as arguments to the program. If any arguments are both in the config file and in the program invocation, the arguments will override the config values. For instance, defining the [--bootstrap|-b] flag in both config and as a flag in the invocation will prefer the flag first, and having api and output defined in config as well as providing 2 arguments to the program when invoking it will opt for the program arguments.

Class document comments

First, the php files with your API endpoints should have this use statement at the top, to handle proper namespacing:

<?php
use Backplane\APIdocGenerator\Annotations;

// ...

The @Annotations\Endpoint annotation both tells the doc generator to consider this class and its methods, and also has a required name parameter that, unsurprisingly, encodes the name of the endpoint:

/**
 * @Annotations\Endpoint(name="Posts")
 */
class postsCall extends apiCall {
    // code...
}

API document comments

Place the @Annotations\EndpointMethod on methods which represent endpoint methods. There more fields for this annotation:

/**
 * @Annotations\EndpointMethod(
 *   name="Method name",
 *   description="This is the method description.",
 *   URI="/path/to/endpoint/method.php",
 *   HTTPMethod="GET",
 *   requiresOAuth=true,
 *   parameters={ ... }
 * )
 */

API parameter annotations

The @Annotations\Parameter annotation is valid only in the parameters field of @Annotations\EndpointMethods. This is its form:

/**
 * @Annotations\Parameter(
 *  name="Parameter name",
 *  description="Parameter description",
 *  type="int",
 *  required=false,
 *  default=0
 * )
 */
)

Alternatively, if the type field is enum, then there are two more required fields:

/**
 * ...
 * type="enum",
 * enum={ ... }
 * ...
 */

And finally, the enumList field is a list of @Annotations\Enum objects, which take this form:

/**
 * @Annotations\Enum(
 *  name="Enumeration name",
 *  description="This field is optional."
 * )
 */

(The description field, as noted, is optional.)

That's all! Now get to documenting!

Example documentation to generate valid IODocs:

<?php
use Backplane\APIdocGenerator\Annotations;

/**
 * @Annotations\Endpoint(name="Posts")
 */
class Posts {
    /**
     * This text is not parsed by the Doctrine Annotations parser.
     *
     * @Annotations/EndpointMethod(
     *   name="getIndex",
     *   description="This gets the hot posts.",
     *   URI="/posts.:format",
     *   HTTPMethod="GET",
     *   requiresOAuth=true,
     *   parameters={
     *     @Annotations/Parameter(
     *       name="offset",
     *       description="Offset from first result",
     *       type="int",
     *       required=false,
     *       default=0
     *     ),
     *     @Annotations/Parameter(
     *       name="limit",
     *       description="Maximum number of results",
     *       type="int",
     *       required=true,
     *       default=100
     *     ),
     *     @Annotations/Parameter(
     *       name="type",
     *       description="Type of post",
     *       type="enum",
     *       enum={
     *         @Annotations/Enum(
     *           name="Photo",
     *           description="A photo post"
     *         ),
     *         @Annotations/Enum(
     *           name="Text",
     *           description="A text post"
     *         ),
     *       },
     *       required=true,
     *       default="Text"
     *     )
     *   },
     * )
     */
    public function getIndex()
    {
        // code here...
    }
}

Converting existing IODocs into PHPDocs

This script also can do a conversion in the opposite direction. Since it doesn't know the structure of your code, however, all it will do is dump all the corresponding PHPDocs comments for your existing API into a file.

To use this feature, run the following command:

/path/to/iodocsgen --phpdocs /path/to/iodocs/data.json outputfile.php

Planned updates

Return type functionality, once I've implemented that in IODocs.
The tests do not offer full coverage and aren't the clearest, unfortunately. But they should check for most functionality. This should be improved.

Happy camping!

backplane / apidoc-generator

Maintainers

Details