hyperf/docs/en/swagger.md

Hyperf Swagger

The hyperf/swagger component is based on zircote/swagger-php for packaging

For a full list of supported annotations, see the OpenApi\Annotations namespace or Documentation site

Installation

composer require hyperf/swagger

Configure

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

parameter name	role
enable	Enables or disables the Swagger document generator
port	The port number of the Swagger document generator
json_dir	The directory where JSON files generated by the Swagger Document Generator are stored
html	Path to the HTML file generated by the Swagger document generator
url	The URL path to the Swagger document
auto_generate	Whether to automatically generate Swagger documents
scan.paths	The path to the API interface file to be scanned, an array

Generate documentation

If auto_generate is configured, the documentation will be generated automatically in the framework initialisation event, without the need to call

php bin/hyperf.php gen:swagger

Use

The OA namespaces that appear below are ``use Hyperf\Swagger\Annotation as OA`''

The framework can start multiple servers, and the routes of each server can be distinguished based on the OA\Hyperferver annotation, and generate different swagger files (using that configuration as the file name).

It can be configured on the controller class or method:

#[OA\HyperfServer('http')]

#[OA\Post(path: '/test', summary: 'POST form example', tags: ['Api/Test'])]
#[OA\RequestBody(
    description: 'Request parameters'.
    content: [
        new OA\MediaType(
            mediaType: 'application/x-www-form-urlencoded'.
            schema: new OA\Schema(
                required: ['username', 'age'].
                properties: [
                    new OA\Property(property: 'username', description: 'User name field description', type: 'string').
                    new OA\Property(property: 'age', description: 'Age field description', type: 'string').
                    new OA\Property(property: 'city', description: 'City field description', type: 'string').
                ]
            ).
        ).
    ].
)]
#[OA\Response(response: 200, description: 'Description of the returned value')]
public function test()
{
}

#[OA\Get(path: '/test', summary: 'GET example', tags: ['Api/Test'])]
#[OA\Parameter(name: 'username', description: 'User name field description', in : 'query', required: true, schema: new OA\Schema(type: 'string'))]
#[OA\Parameter(name: 'age', description: 'Age field description', in : 'query', required: true, schema: new OA\Schema(type: 'string'))]
#[OA\Parameter(name: 'city', description: 'City field description', in : 'query', required: false, schema: new OA\Schema(type: 'string'))]
#[OA\Response(
    response: 200.
    description: 'Description of the returned value'.
    content: new OA\JsonContent(
        example: '{"code":200, "data":[]}'
    ).
)]
public function list(ConversationRequest $request): array
{
}