PHPAPIDocumentor is a PHP-based API documentation generator that converts structured API annotations in PHP source code into a browsable API reference.
The project can be distributed as a standalone PHAR, making it suitable for documentation generation in local development environments and automated build pipelines.
- Generates browsable HTML API documentation from PHP DocBlock annotations
- Supports API groups, names, versions, descriptions, permissions, request bodies, headers, examples, and responses
- Generates request examples for supported clients
- Supports multiple server environments
- Supports configurable documentation generation through JSON configuration
- Produces a standalone documentation website
- Can be distributed as a portable PHAR executable
- PHP CLI
- PHP Phar support enabled
- A valid
phpapidoc.jsonconfiguration file - PHP source code containing supported API annotations
Check the installed PHP version with:
php --versionDownload the latest pad.phar release and place it in your development
environment.
Run it with:
php pad.phar -c phpapidoc.jsonThe PHAR can also be placed in a directory included in your system
PATH.
Clone the repository and install any dependencies required by the repository configuration.
The PHAR distribution is recommended when you only need to generate documentation. Use the source distribution when developing or modifying PHPAPIDocumentor itself.
PHPAPIDocumentor requires a configuration file.
php pad.phar -c phpapidoc.jsonThe configuration option may also be supplied using the supported long-form option:
php pad.phar --config phpapidoc.jsonA successful build generates the configured API specification and HTML documentation.
A typical project uses:
phpapidoc.json
The configuration controls documentation generation, including server environments and output settings.
Multiple server environments can be defined in one configuration:
{
"servers": {
"production": {
"http2": true,
"protocol": "https",
"host": "api.example.com"
},
"development": {
"http2": true,
"protocol": "https",
"host": "api.example.test"
}
}
}The generated documentation can use the current hostname to determine the configured server environment.
This makes it possible to deploy the same documentation build to different environments without maintaining separate documentation builds.
PHPAPIDocumentor uses structured DocBlocks to describe API endpoints.
A basic endpoint can be documented as follows:
/**
* @api {get} /users Get Users
* @apiGroup Users
* @apiName GetUsers
* @apiVersion 1.0.0
* @apiDescription Returns a list of users.
*/A more detailed endpoint can define request bodies, permissions, examples, and reusable responses:
/**
* @api {post} /users Create User
* @apiGroup Users
* @apiName CreateUser
* @apiVersion 1.0.0
* @apiDescription Creates a new user account.
* @apiPermission admin
*
* @apiBody {String} username The username of the user.
* @apiBody {String} password The password of the user.
* @apiBody {String} email The email address of the user.
*
* @apiExamples [http:HTTP;curl:CURL;php_curl:PHP (cURL)]
* @apiUse CreateUserResponse
*/See the project's sample annotations and supported documentation syntax for the complete annotation reference.
A successful build produces a browsable HTML API reference and its associated specification/assets.
A typical output directory may look like:
docs/
├── index.html
├── padspec.json
├── assets/
└── ...
The generated documentation can be served by any web server capable of serving static files.
For example:
https://api.example.com/docs/
Server configuration determines the host and protocol used by generated URLs. The API route itself must also be represented correctly by the endpoint definitions or relevant configuration.
For an API mounted at:
/console/api/v1
the generated request URL should include that base path:
https://api.example.com/console/api/v1/users
rather than:
https://api.example.com/users
Always verify generated request URLs against the application's actual routing configuration before publishing documentation.
After generating documentation, serve the output directory with PHP's built-in server:
php -S localhost:8080 -t docsThen open:
http://localhost:8080/
A typical source distribution may contain:
.
├── src/
├── inc/
├── sample/
├── phpapidoc.json
├── pad.phar
└── README.md
The exact structure may vary between source and release distributions.
The PHAR provides a portable command-line distribution of PHPAPIDocumentor.
Example:
php pad.phar -c phpapidoc.jsonThe PHAR contains the documentor runtime. The API project's source files and configuration remain inputs to the documentation build.
Clone the repository:
git clone <repository-url>
cd <repository-directory>Before submitting or releasing changes, verify that:
- The PHAR starts successfully.
- The configuration file is accepted.
- API annotations are parsed correctly.
- Multiple server configurations work correctly.
- The generated documentation loads without JavaScript errors.
- Generated request URLs match the deployed API.
- The generated HTML and specification files are complete.
Releases are distributed as versioned PHAR artifacts.
Example:
v1.0.0
The release artifact is:
pad.phar
Release notes should document significant changes, compatibility requirements, fixes, and changes affecting generated documentation.
Generated API documentation can expose endpoint names, request structures, permissions, headers, application behavior, and other implementation details.
Do not publish internal API documentation publicly unless the API and its documentation are intentionally intended for public consumption.
For internal APIs, protect the documentation endpoint with appropriate authentication and authorization controls.
Documentation does not provide API security. API endpoints must enforce their own authentication, authorization, validation, and access-control requirements.
See the repository's license file for the applicable license and redistribution terms.
Contributions are welcome.
When submitting changes:
- Keep changes focused and maintainable.
- Preserve existing annotation conventions.
- Test generated documentation before submitting changes.
- Include relevant configuration or fixture changes when required.
- Document behavior changes that affect users of PHPAPIDocumentor.
Release-specific changes are documented in the repository's GitHub Releases and changelog documentation where applicable.
PHPAPIDocumentor
A command-line PHP API documentation generator for producing structured and browsable API references.