README

PHP autodoc automatically generates up-to-date OpenAPI 3.1.0 documentation and TypeScript types directly from your PHP code – no PHPDoc annotations required.

Instead of relying on manually written comments, PHP autodoc reads your actual PHP code and native types to extract accurate type information. PHPDoc annotations are supported if present, but completely optional.

For Laravel projects, autodoc-laravel offers seamless integration with routes, request validation, database models, API resources, and more.

Visit phpautodoc.com to see full documentation.

TypeScript export

Keep your frontend and backend in sync – define your types once in PHP and let PHP autodoc generate the matching TypeScript types automatically.

PHP autodoc supports exporting enums, classes, PHPStan type aliases, request/response structures and even custom PHPDoc type expressions as TypeScript types. PHP autodoc-laravel extends this functionality by offering support for Laravel models and other Laravel-specific structures that need custom handling.

See TypeScript section in our documentation for more info and examples.

How it works?

PHP autodoc uses PHP parser and PHPDoc parser to analyze your code and convert it into AutoDoc\DataTypes\Type objects. These objects can be used in your custom PHP autodoc extensions and are also utilized in generating OpenAPI 3.1.0 schemas and TypeScript types. If you are using a static analysis tool like PHPStan, you will find that autodoc works well without any changes to your codebase.

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.