# 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](https://github.com/zircote/swagger-php/blob/master/src/Annotations) or [Documentation site](https://zircote.github.io/swagger-php/guide/annotations.html#arrays-and-objects)


## 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
```shell
php bin/hyperf.php gen:swagger
```

## Use

> The SA namespaces that appear below are `use Hyperf\Swagger\Annotation as SA`

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

It can be configured on the controller class or method:
```php
#[SA\HyperfServer('http')]
```

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

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

### Combination validator

In the `SA\Property` and `SA\QueryParameter` annotation, we can add `rules` parameters,

and then cooperate with `SwaggerRequest` to verify the validity of the parameters in the middleware.


```php
<?php
namespace App\Controller;

use App\Schema\SavedSchema;
use Hyperf\Swagger\Request\SwaggerRequest;
use Hyperf\Di\Annotation\Inject;
use Hyperf\Swagger\Annotation as SA;

#[SA\HyperfServer(name: 'http')]
class CardController extends Controller
{
    #[SA\Post('/user/save', summary: 'Save user info', tags: ['user-management'])]
    #[SA\QueryParameter(name: 'token', description: 'auth token', type: 'string', rules: 'required|string')]
    #[SA\RequestBody(content: new SA\JsonContent(properties: [
        new SA\Property(property: 'nickname', type: 'integer', rules: 'required|string'),
        new SA\Property(property: 'gender', type: 'integer', rules: 'required|integer|in:0,1,2'),
    ]))]
    #[SA\Response(response: '200', content: new SA\JsonContent(ref: '#/components/schemas/SavedSchema'))]
    public function info(SwaggerRequest $request)
    {
        $result = $this->service->save($request->all());

        return $this->response->success($result);
    }
}
```