Boost PHP API Docs with Apidoc: Installation, Annotations, and Usage Guide

What Is Apidoc?

Apidoc is a PHP Composer extension that generates API documentation by parsing annotations. It works with frameworks such as Laravel, ThinkPHP, Hyperf, and Webman, offering features like online debugging, mock data, event handling, JSON/TypeScript generation, and code scaffolding to speed up API development.

Key Features

Zero‑configuration, ready‑to‑use after installation.

Supports class, method, and property annotations, including database field references.

Online interface testing with global request, mock parameters, and event handling.

Password‑protected access and document caching.

Multi‑application and multi‑version support.

Group/Tag organization for controllers and endpoints.

Markdown (.md) documentation rendering.

Automatic JSON and TypeScript client generation.

Code generator for scaffolding controllers, models, and tables.

Annotation Basics

Annotations add structured, machine‑readable metadata to classes, methods, functions, parameters, properties, or constants. PHP 8 introduces native attributes using the #[...] syntax, while Apidoc also supports its original @Annotation style.

Examples:

<?php
#[ClassAnnotation]
class Foo {}

<?php
class Foo {
    #[MethodAnnotation]
    public function bar() {
        // some code
    }
}

<?php
class Foo {
    #[PropertyAnnotation]
    private $bar;
}

Installation

Run the Composer command: composer require hg/apidoc Download the front‑end UI (e.g., from Gitee or GitHub) and copy the apidoc folder into the public directory of your Webman project.

Access http://127.0.0.1:8787/apidoc/index.html to verify the UI loads.

Configuration

After installation, a configuration file is generated at config/plugin/hg/apidoc/app.php. Important keys include:

<?php
return [
    'enable' => true,
    'apidoc' => [
        // optional title and description
        'title' => 'Open Source Tech Stack',
        'desc'  => 'CMS API documentation',
        // required applications/versions
        'apps' => [
            [
                'title' => 'CMS API',
                'path'  => 'app\admin\controller',
                'key'   => 'admin',
            ],
            [
                'title' => 'Demo Docs',
                'path'  => 'app\controller',
                'key'   => 'api',
            ],
        ],
    ],
];

Explanation of the three main fields: apps: defines each documentation group (e.g., CMS API, Demo Docs). path: the directory where controller classes reside. key: a unique identifier for the group, used in URLs.

Writing Annotated Controllers

Create a controller (e.g., LoginController.php) under app/admin/controller and import the annotation namespace:

<?php
/**
 * @desc LoginController
 */
declare(strict_types=1);

namespace app\admin\controller;

use support\Request;
use hg\apidoc\annotation as Apidoc;
use support\Response;

/**
 * @Apidoc\Title("Login Management")
 */
class LoginController {
    /**
     * @Apidoc\Title("1.0 Issue Token")
     * @Apidoc\Url("admin/login/token")
     * @Apidoc\Method("POST")
     * @Apidoc\Query("username", type="string", require=true, desc="Account", default="Tinywan")
     * @Apidoc\Query("password", type="string", require=true, desc="Password", default="123456")
     * @Apidoc\Returned("access_token", type="string", desc="Access token")
     */
    public function token(Request $request): Response {
        var_dump($request->all());
        return json(['code'=>0,'msg'=>'success','data'=>['access_token'=>time()]]);
    }

    /**
     * @Apidoc\Title("2.0 User Info")
     * @Apidoc\Url("admin/login/user")
     * @Apidoc\Method("GET")
     * @Apidoc\Query("id", type="int", require=true, desc="User ID", default=0)
     */
    public function user(Request $request): Response {
        return json(['code'=>0,'msg'=>'success','data'=>['username'=>'Open Source Tech Stack','age'=>24]]);
    }
}

These annotations generate two endpoints: admin/login/token (POST) and admin/login/user (GET), which appear in the generated documentation.

Viewing and Debugging the API Docs

After coding, open http://127.0.0.1:8787/apidoc/index.html. The UI lists the defined endpoints with request parameters and sample responses. Clicking an endpoint switches to debug mode, allowing you to send test requests directly from the browser.

Conclusion

Apidoc provides a straightforward way to generate and test API documentation for PHP projects, especially those built with Webman, Laravel, or similar frameworks. By leveraging PHP 8 native attributes or Apidoc’s original annotation syntax, developers can keep API specifications close to the source code, improving maintainability and reducing manual documentation effort.