Swagger-PHP for PHP: Complete Guide with Examples

What is Swagger-PHP and why is it needed?

Swagger-PHP is a powerful PHP library for automatically generating REST API documentation in OpenAPI format (formerly known as Swagger). Instead of manually writing documentation in YAML or JSON, you describe the API directly in the code using PHPDoc annotations. The library analyzes these annotations and generates a complete OpenAPI specification, which can be visualized using Swagger UI, ReDoc, or other tools.

Why is this needed?

\n
• Automation: Documentation is always synchronized with the code. Changed an endpoint — updated the annotation, and the documentation is ready.
\n
• Standardization: OpenAPI is an industry standard for describing REST APIs, supported by hundreds of tools.
\n
• Convenience for frontend: Client application developers can import the specification into Postman, Insomnia, or generate client code.
\n
• Testing: The specification can be used for automated API testing.
\n
• Interactive documentation: Swagger UI allows testing endpoints directly from the browser.
\n

Installing Swagger-PHP

Installation is done via Composer — the standard package manager for PHP. Open a terminal in the root directory of your project and run:

composer require zircote/swagger-php

If you are using Laravel, Symfony, or another framework, the installation is the same. After installation, the folder vendor/zircote/swagger-php will appear in your project.

Additional (optional): To visualize the documentation, you will need Swagger UI. You can install it via npm:

npm install swagger-ui-dist

Or simply download a ready-made build from the official Swagger website.

Quick start with code example

Let's create a simple API for managing a task list (Todo List) and generate documentation for it.

Step 1: Create a file index.php with your API:

<?php\n/**\n * @OA\\Info(\n *     title="Todo API",\n *     version="1.0.0",\n *     description="Simple API for managing tasks"\n * )\n * @OA\\Server(\n *     url="http://localhost:8000",\n *     description="Local server"\n * )\n */\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Get(\n *     path="/tasks",\n *     summary="Get a list of all tasks",\n *     @OA\\Response(\n *         response=200,\n *         description="Successful response",\n *         @OA\\JsonContent(\n *             type="array",\n *             @OA\\Items(ref="#/components/schemas/Task")\n *         )\n *     )\n * )\n */\nfunction getTasks() {\n    $tasks = [\n        ['id' => 1, 'title' => 'Buy milk', 'completed' => false],\n        ['id' => 2, 'title' => 'Write an article', 'completed' => true]\n    ];\n    header('Content-Type: application/json');\n    echo json_encode($tasks);\n}\n\n/**\n * @OA\\Post(\n *     path="/tasks",\n *     summary="Create a new task",\n *     @OA\\RequestBody(\n *         required=true,\n *         @OA\\JsonContent(ref="#/components/schemas/TaskInput")\n *     ),\n *     @OA\\Response(\n *         response=201,\n *         description="Task created",\n *         @OA\\JsonContent(ref="#/components/schemas/Task")\n *     )\n * )\n */\nfunction createTask() {\n    // Task creation logic\n    echo json_encode(['id' => 3, 'title' => 'New task', 'completed' => false]);\n}\n\n/**\n * @OA\\Schema(\n *     schema="Task",\n *     @OA\\Property(property="id", type="integer"),\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property="completed", type="boolean")\n * )\n * @OA\\Schema(\n *     schema="TaskInput",\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property