mirror of
https://gitee.com/hyperf/hyperf.git
synced 2024-12-02 11:48:08 +08:00
87 lines
3.2 KiB
Markdown
87 lines
3.2 KiB
Markdown
|
# 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 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:
|
||
|
|
```php
|
||
|
|
#[OA\HyperfServer('http')]
|
||
|
|
```
|
||
|
|
|
||
|
|
``` php
|
||
|
|
#[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()
|
||
|
|
{
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
```php
|
||
|
|
#[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
|
||
|
|
{
|
||
|
|
}
|
||
|
|
```
|