Swagger-PHP for PHP: Complete Guide with Examples

1. What It Is and Why You Need It

Swagger-PHP is a powerful library for the PHP language that allows you to automatically generate an OpenAPI (formerly Swagger) specification of your REST API based on annotations in the code. Instead of manually writing huge YAML or JSON files describing all endpoints, parameters, data models, and responses, you simply add special comments (annotations) directly into the controllers, models, and routes of your PHP application. The library analyzes these annotations and creates a complete, valid OpenAPI specification that can be exported in JSON or YAML format.

Why is this needed? In modern web development, the API is a key interface for interaction between the frontend, mobile applications, and third-party services. Keeping documentation up to date is a constant headache. Swagger-PHP solves this problem by linking documentation directly to the source code. If you change the logic of an endpoint, you also change the annotation next to it. The documentation always matches the actual behavior of the API. This saves hours of work, reduces the number of integration errors, and makes your project transparent for new developers.

Additionally, the generated OpenAPI specification can be used with dozens of tools: Swagger UI (interactive documentation where you can test requests directly from the browser), client SDK generators for JavaScript, Python, Java, and other languages, testing and validation tools (e.g., Postman or Insomnia), and for automatic generation of mock servers. Swagger-PHP is the de facto standard for documenting PHP APIs.

2. Installation

Installation is done via Composer, the standard package manager for PHP. Run the following command in the root of your project:

composer require zircote/swagger-php

After installation, the directory vendor/zircote/swagger-php will appear in your project. The library requires PHP version 8.0 or higher (to support modern PHP 8 attribute annotations). If you are using an older version of PHP, you will need library version 3.x, but it is strongly recommended to upgrade to PHP 8+ and use the latest version of Swagger-PHP (4.x).

3. Quick Start — Minimal Working Example

Let's create a simple controller with one endpoint and generate an OpenAPI specification for it.

Step 1: Create the file src/Controllers/UserController.php

<?php\n\nnamespace App\\Controllers;\n\nuse OpenApi\\Attributes as OA;\n\nclass UserController\n{\n    #[OA\\Get(\n        path: '/api/users/{id}',\n        summary: 'Get user by ID',\n        tags: ['Users']\n    )]\n    #[OA\\Parameter(\n        name: 'id',\n        in: 'path',\n        required: true,\n        schema: new OA\\Schema(type: 'integer')\n    )]\n    #[OA\\Response(\n        response: 200,\n        description: 'Successful response',\n        content: new OA\\JsonContent(\n            properties: [\n                new OA\\Property(property: 'id', type: 'integer'),\n                new OA\\Property(property: 'name', type: 'string'),\n                new OA\\Property(property: 'email', type: 'string')\n            ]\n        )\n    )]\n    public function getUser(int $id): array\n    {\n        // Here should be the logic for getting the user from the database\n        return [\n            'id' => $id,\n            'name' => 'John Doe',\n            'email' => 'john@example.com'\n        ];\n    }\n}

Step 2: Create a script to generate the specification generate-docs.php

<?php\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\nuse OpenApi\\Generator;\n\n// Specify the directory where our