README.md

php-gen-doc-api

Generate documentation for PHP API with Annotations. No dependency. No framework required.

• Preview
• Requirements
• Installation
• Usage
• Options
• Annotations
• Custom output html
• Known issues
• Acknowledgment

Preview

You can see a sample generated documentation based on class Client on http://zckrs.github.io/php-gen-doc-api/

Requirements

No dependency. No framework required. View on Packagist.org

You just need PHP >= 5.3.2.

Installation

The recommended installation is via composer. Just add the following line to your composer.json :

{
    ...
    "require": {
        ...
        "zckrs/php-gen-doc-api": "@dev"
    }
}

$ php composer.phar update

Usage

• Duplicate the genDocApi.php file in your project root for example.
• Set options in this new file.
• Execute it via CLI : php genDocApi.php
• You get a new HTML file. (With default options stored in web/index.html)

Options

output_file

The name of the generated file (default : index.html).

output_dir

The directory to store the html file (default : /web).

template_dir

The directory to store the views (default : /src/Resources/views).

You can override view. See how to custom output HTML

asset_dir

The directory to store the assets (default : /src/Resources/assets).

You can override asset. See how to custom output HTML

Annotations

• @ApiDescription(section="...", description="...")
• @ApiMethod(type="(get|post|put|delete")
• @ApiRoute(name="...")
• @ApiParams(name="...", type="...", nullable=(true|false), description="...", sample="...")
• @ApiReturnRootSample(sample="{ ... }")
• @ApiReturnObject(section="...", name="...", type="...", desc="...", note="...", link="...")

Custom output HTML

What includes in default layout.html :

• Bootstrap v3.1.1
• jQuery v1.10.2
• Google Code Prettify

How to custom output HTML:

1. Create a main directory for views.
2. Define option template_dir in genDocApi.php.
3. Put custom view with same model tree. Details Views
4. Each view contains some {{ variables }}

Known issues

If you have some problems or improvements, contact me via GitHub.

Acknowledgment

This project is inspired by Calinrada's php-apidoc based on Swagger and use Extractor.php written by Eriknyk