README

PHP autodoc automatically generates OpenAPI 3.1.0 documentation for your PHP projects by analyzing your codebase. This ensures your API docs are always up-to-date and easy to maintain.

For Laravel projects, autodoc-laravel provides support for Laravel routes, request validation, database models, API resources and more.

Visit phpautodoc.com to see full documentation.

How it works?

PHP autodoc uses native PHP types and PHPDoc annotations to determine data types to show in generated documentation. If you are using a static analysis tool like PHPStan, you will find that autodoc works well without any changes to your code base.

Installation

Using Laravel

To install PHP autodoc in a Laravel project, simply install the 421c/autodoc-laravel package.

composer require 421c/autodoc-laravel

Then copy configuration file to your project using the command below.

php artisan vendor:publish --provider="AutoDoc\Laravel\Providers\AutoDocServiceProvider"

Open your config/autodoc.php file and set openapi_export_dir setting to a directory where you want to save OpenApi 3.1.0 schema JSON files generated by this package. Make sure this directory exists and is writable.

In your configuration file you can also specify URL to your API docs page with laravel.url setting. If you left it unchanged, you can visit /api-docs route to see the generated documentation.

Manual installation

If you are not using Laravel framework, you can set up PHP autodoc using the following steps:

1. Install 421c/autodoc-php package.

composer require 421c/autodoc-php

1. Create a class that extends AutoDoc\AbstractRouteLoader and define a getRoutes method. See more information in code comments below.

use AutoDoc\AbstractRouteLoader;
use AutoDoc\Route;

class RouteLoader extends AbstractRouteLoader
{
    public function getRoutes(): iterable
    {
        /**
         * In this method you may `return` an array of routes or `yield`
         * the routes using generator syntax like in this example.
         */

        yield new Route(
            uri: '/api/test/x',
            method: 'get',
            className: TestController::class,
            classMethod: 'x',
        );

        /**
         * You may construct the Route objects so that they point to either
         * class methods or closures.
         */

        yield new Route(
            uri: '/api/test/y',
            method: 'post',
            closure: (
                /**
                 * @return array<object{test: bool}>
                 */
                function () {
                    // ...
                }
            ),
        );
    }
}

1. Copy the configuration file located at vendor/421c/autodoc-php/config/autodoc.php to your project.

2. Find route_loader setting and set it to your route loader class from 2. step.

/**
 * Class that will be used to load and analyze routes.
 * This class must extend `AutoDoc\AbstractRouteLoader`.
 */
'route_loader' => RouteLoader::class,

1. Find openapi_export_dir setting and set it to directory where you want to store OpenApi 3.1.0 schema JSON files generated by this package. Make sure it exists and is writable.

/**
 * Directory where OpenApi schema files will be exported.
 */
'openapi_export_dir' => '/path/to/openapi',

1. Depending on your project setup, define a new route that will accept a GET request and return the OpenApi JSON schema. In this route, add the following code:

$autodocConfig = new \AutoDoc\Config(require '/path/to/your/config/autodoc.php');
$workspace = \AutoDoc\Workspace::getDefault($autodocConfig);

echo $workspace->getJson();

You can read more about workspaces here.

1. Create another route that will be used to view your documentation. In this route, add the following code:

$autodocConfig = require '/path/to/your/config/autodoc.php';

// The route you created in previous step.
$openApiUrl = '/docs/openapi-json';

$docViewer = new \AutoDoc\DocViewer(
    title: $autodocConfig['api']['title'],
    openApiUrl: $openApiUrl,
    theme: $autodocConfig['ui']['theme'],
    logo: $autodocConfig['ui']['logo'],
    hideTryIt: $autodocConfig['ui']['hide_try_it'],
);

$docViewer->renderPage();

Now you can visit this route and see the generated documentation.

To improve the generated documentation, see tips to improve the generated documentation.