README

Swagger/OpenAPI integration for Hyperf. The package uses PHP attributes to scan Hyperf controllers and generates OpenAPI JSON documents, with an optional YAML output.

Requirements

PHP 8.2 or later
Hyperf 3.2
zircote/swagger-php 6.x (the compatibility matrix also covers 4.x)

Installation

composer require ussaaass/hyperf-swagger

If request validation is needed, install Hyperf Validation as well:

composer require hyperf/validation

Publish the package configuration:

php bin/hyperf.php vendor:publish hyperf/swagger

The default configuration is written to config/autoload/swagger.php.

Annotating a controller

Each controller can be assigned to a Hyperf server with HyperfServer. The name must match a key in swagger.server.

<?php

namespace App\Controller;

use Hyperf\Swagger\Annotation as OA;
use Hyperf\Swagger\Request\SwaggerRequest;

#[OA\Info(title: 'Example API', version: '1.0.0')]
#[OA\HyperfServer('http')]
class UserController
{
    #[OA\Get('/users', summary: 'List users', tags: ['users'])]
    public function index(SwaggerRequest $request): array
    {
        return [];
    }
}

The package provides Get, Post, Put, Patch, Delete, Head, and Options attributes, together with OpenAPI attributes such as Info, Schema, Response, RequestBody, JsonContent, and Property.

Request validation

Use SwaggerRequest in a controller method and put validation rules on the corresponding Swagger attributes:

#[OA\Post('/users', summary: 'Create user')]
#[OA\QueryParameter(
    name: 'name',
    required: true,
    rules: 'required|string|max:50',
    attribute: 'user name',
)]
public function create(SwaggerRequest $request): array
{
    return [];
}

Rules can also be placed on OA\Property inside a request body. SwaggerRequest reads them through ValidationCollector and exposes them to Hyperf Validation.

Configuration

The important defaults are:

return [
    'enable' => true,
    'port' => 9500,
    'url' => '/swagger',
    'auto_generate' => true,
    'json_dir' => BASE_PATH . '/storage/swagger',
    'yaml_dir' => null,
    'scan' => [
        'paths' => null,
    ],
    'server' => [
        'http' => [
            'servers' => [
                ['url' => 'http://127.0.0.1:9501'],
            ],
            'info' => [
                'title' => 'Example API',
                'version' => '1.0.0',
            ],
        ],
    ],
];

server is keyed by the value passed to #[OA\HyperfServer(...)]. The generated JSON is saved as <server>.json. Set yaml_dir to a directory to generate <server>.yaml as well.

Generating the specification

When auto_generate is enabled, the specification is generated during application boot. It can also be generated explicitly:

php bin/hyperf.php gen:swagger

To generate a schema class from a Hyperf model:

php bin/hyperf.php gen:swagger-schema --model App\\Model\\User

With the default server configuration, Swagger UI is available at:

http://127.0.0.1:9500/swagger?search=/http.json

The JSON document is served from the Swagger server; YAML files are intended for tooling and distribution.

Compatibility tests

The repository contains a PHP 8.2/8.4/8.5 matrix for both swagger-php 4.x and 6.x:

composer update
vendor/bin/phpunit -c phpunit.xml.dist

COMPOSER=composer.swagger-php-6.json composer update
vendor/bin/phpunit -c phpunit.xml.dist

The 6.x path is the default dependency. The 4.x path is retained as a compatibility test and verifies backward compatibility with existing installations.

License

MIT

ussaaass / hyperf-swagger

Package info

Security

Statistics