基于 Hyperf 框架的 swagger 文档生成组件
- 声明参数类型完成自动注入,参数映射到PHP类,根据类和注解自动生成Swagger文档
- 代码可维护性好,扩展性好
- 支持api token认证
- 模型类需要手工编写
composer require tangwei/apidocs
php bin/hyperf.php vendor:publish tangwei/apidocs
config/autoload/apidocs.php
return [
// enable false 将不会启动 swagger 服务
'enable' => env('APP_ENV') !== 'prod',
'output_dir' => BASE_PATH . '/runtime/swagger',
//认证api key
//'security_api_key' => ['Authorization'],
//全局responses
'responses' => [
401=>['description'=>'Unauthorized']
],
// swagger 的基础配置
'swagger' => [
'swagger' => '2.0',
'info' => [
'description' => 'swagger api desc',
'version' => '1.0.0',
'title' => 'API DOC',
],
'host' => '',
'schemes' => [],
],
];
php bin/hyperf.php start
[INFO] Swagger Url at 0.0.0.0:9531/swagger
[INFO] TaskWorker#1 started.
[INFO] Worker#0 started.
[INFO] HTTP Server listening at 0.0.0.0:9531
看到
Swagger Url
显示,表示文档生成成功,访问/swagger
即可以看到swagger页面
定义一个类,增加类型属性 实现
implements
对应的接口即可 命名空间:Hyperf\DTO\Contracts
- Body参数
class DemoBodyRequest implements RequestBody{}
- GET参数
class DemoQuery implements RequestQuery{}
- 表单请求
class GoodsFormData implements RequestFormData{}
注意: 一个方法中,不要同时注入RequestBody和RequestFormData
<?php
declare(strict_types=1);
namespace App\Controller;
use App\DTO\Request\DemoBodyRequest;
use App\DTO\Request\DemoFormData;
use App\DTO\Request\DemoQuery;
use Hyperf\ApiDocs\Annotation\Api;
use Hyperf\ApiDocs\Annotation\ApiOperation;
use App\DTO\Response\Contact;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\PostMapping;
/**
* @Controller(prefix="/demo")
* @Api(tags="demo管理")
*/
class DemoController
{
/**
* @ApiOperation(summary="查询")
* @PostMapping(path="index")
* @param DemoQuery $request
* @return Contact
*/
public function index(DemoQuery $request) : Contact
{
$contact = new Contact();
var_dump($request);
return $contact;
}
/**
* @ApiOperation(summary="查询单条记录")
* @GetMapping(path="find/{id}/and/{in}")
*/
public function find(int $id,int $in) : array
{
return ['$id'=>$id,'$in'=>$in];
}
/**
* @ApiOperation(summary="提交body数据和get参数")
* @PostMapping(path="add")
* @param DemoBodyRequest $request
* @param DemoQuery $request2
*/
public function add(DemoBodyRequest $request,DemoQuery $request2) :Contact
{
var_dump($request2);
var_dump($request);
return new Contact();
}
/**
* @ApiOperation(summary="表单提交")
* @PostMapping(path="fromData")
* @param DemoFormData $formData
* @return bool
*/
public function fromData(DemoFormData $formData) : bool
{
var_dump($formData);
return true;
}
}
<?php
namespace App\DTO\Request;
use Hyperf\ApiDocs\Annotation\ApiModelProperty;
use Hyperf\DTO\Contracts\RequestBody;
class DemoBodyRequest implements RequestBody
{
/**
* @ApiModelProperty(value="demo名称")
*/
public ?string $demoName = null;
/**
* @ApiModelProperty(value="价格",required=true)
*/
public float $price;
/**
* @ApiModelProperty(value="示例id",required=true)
* @var int[]
*/
public array $demoId;
/**
* 需要绝对路径
* @ApiModelProperty(value="地址")
* @var \App\DTO\Address[]
*/
public array $addressArr;
}
/**
* @ApiOperation(summary="文件提交")
* @ApiFormData(name="file",type="file")
* @PostMapping(path="fileAdd")
*/
public function fileAdd(): bool
{
return true;
}
其他例子,请查看example