zckrs/php-gen-doc-api

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

This package's canonical repository appears to be gone and the package has been frozen as a result.

v1.0.1 2014-06-19 13:42 UTC

Requires

• php: >=5.3.2

Requires (Dev)

• phpunit/phpcov: 2.0.*@dev
• satooshi/php-coveralls: 0.7.*@dev

MIT

• Mehdy Dara

• generator
• documentation
• php
• api
• agnostic

README

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 Client and Document:

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

apiName

The name of the current API, displayed at the top of the generated file (default: php-gen-doc-api).

apiDescription

The description of the current API, displayed on the top of the generated file (default: no value).

outputFile

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

outputDir

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

templateDir

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

You can override view. See how to custom output HTML

assetDir

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