Swagger/OpenAPI Generation for PHP

Swagger/OpenAPI Generation for PHP: A Complete Overview of Tools

In modern web development, creating high-quality API documentation has become not just good practice, but a necessity. Swagger (now known as OpenAPI) is a standard for describing RESTful APIs that allows you to automate the generation of documentation, client SDKs, and test console interfaces. In this article, we will take a detailed look at how to use Swagger/OpenAPI for PHP projects, what libraries exist, and how to properly implement them.

What is Swagger/OpenAPI?

The OpenAPI Specification (OAS) is a specification that defines a standard for describing REST APIs in JSON or YAML format. It allows you to:

Automatically generate interactive documentation (Swagger UI);
Create client libraries for various programming languages;
Validate the correctness of requests and responses;
Integrate with CI/CD pipelines.

Main Libraries for PHP

There are several popular libraries for working with OpenAPI in PHP. Let's look at each of them in detail.

1. Swagger-PHP (zircote/swagger-php)

This is the most popular and mature library for generating OpenAPI specifications from PHP annotations. It allows you to describe the API directly in the code, which simplifies keeping the documentation up to date.

Installation:

composer require zircote/swagger-php

Usage example:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="My API", *     version="1.0.0", *     description="Example API for Swagger demonstration" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Production server" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="Get a list of users",     *     @OA\\Response(     *         response=200,     *         description="Successful response",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // Logic for getting users    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // Empty method for describing the schema    }}

// Generating the specification$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

This library allows you not only to describe the API but also to automatically generate server code based on the OpenAPI specification. It is especially useful when using the Design-First development principle.

Installation:

composer require thecodingmachine/openapi-server

Server generation example:

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// Loading the specification$spec = json_decode(file_get_contents('openapi.json'), true);

// Creating the server$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// Handling the request$response = $server->handle($request);?>