PHPackages wayhood/hyperf-apidocs - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. wayhood/hyperf-apidocs ActiveLibrary[API Development](/categories/api) wayhood/hyperf-apidocs ====================== A swagger library for Hyperf. v3.0.0(4y ago)018MITPHPPHP >=8.0 Since Oct 14Pushed 4y agoCompare [ Source](https://github.com/wayhood/api-docs)[ Packagist](https://packagist.org/packages/wayhood/hyperf-apidocs)[ RSS](/packages/wayhood-hyperf-apidocs/feed)WikiDiscussions master Synced 4w ago READMEChangelog (1)Dependencies (8)Versions (13)Used By (0) PHP Swagger Api Docs -------------------- [](#php-swagger-api-docs) 基于 [Hyperf](https://github.com/hyperf/hyperf) 框架的 swagger 文档生成组件 ##### 优点 [](#优点) - 声明参数类型完成自动注入，参数映射到PHP类，根据类和注解自动生成Swagger文档 - 代码可维护性好，扩展性好 - 支持数组，递归，嵌套和数据校验 - 支持api token认证 - 支持PHP8原生注解 使用须知 ---- [](#使用须知) - php >= 8.0 - 控制器中方法尽可能返回类,这样会更好的生成文档 - 当返回类的结果满足不了时,用 #\[ApiResponse\] 注解 - 模型类需要手工编写 安装 -- [](#安装) ``` composer require tangwei/apidocs ``` 使用 -- [](#使用) #### 1. 发布配置文件 [](#1-发布配置文件) ``` php bin/hyperf.php vendor:publish tangwei/apidocs ``` ##### 1.1 配置信息 [](#11-配置信息) > config/autoload/api\_docs.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' => [], ], ]; ``` ### 2. 直接启动框架(需要有http服务) [](#2-直接启动框架需要有http服务) ``` php bin/hyperf.php start [INFO] Swagger Url at 0.0.0.0:9501/swagger [INFO] TaskWorker#1 started. [INFO] Worker#0 started. [INFO] HTTP Server listening at 0.0.0.0:9501 ``` > 看到`Swagger Url`显示，表示文档生成成功，访问`/swagger`即可以看到swagger页面 ### 3. 使用 [](#3-使用) 注解 -- [](#注解) > 命名空间:`Hyperf\DTO\Annotation\Contracts` #### RequestBody [](#requestbody) - 获取Body参数 ``` public function add(#[RequestBody] DemoBodyRequest $request){} ``` ### RequestQuery [](#requestquery) - 获取GET参数 ``` public function add(#[RequestQuery] DemoQuery $request){} ``` ### RequestFormData [](#requestformdata) - 获取表单请求 ``` public function fromData(#[RequestFormData] DemoFormData $formData){} ``` - 获取文件(和表单一起使用) ``` #[ApiFormData(name: 'photo', type: 'file')] ``` - 获取Body参数和GET参数 ``` public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query){} ``` > 注意: 一个方法，不能同时注入RequestBody和RequestFormData 示例 -- [](#示例) ### 控制器 [](#控制器) ``` #[Controller(prefix: '/demo')] #[Api(tags: 'demo管理', position: 1)] class DemoController extends AbstractController { #[ApiOperation(summary: '查询')] #[PostMapping(path: 'index')] public function index(#[RequestQuery] #[Valid] DemoQuery $request): Contact { $contact = new Contact(); $contact->name = $request->name; var_dump($request); return $contact; } #[PutMapping(path: 'add')] #[ApiOperation(summary: '提交body数据和get参数')] public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query) { var_dump($query); return json_encode($request, JSON_UNESCAPED_UNICODE); } #[PostMapping(path: 'fromData')] #[ApiOperation(summary: '表单提交')] #[ApiFormData(name: 'photo', type: 'file')] #[ApiResponse(code: '200', description: 'success', className: Address::class, type: 'array')] public function fromData(#[RequestFormData] DemoFormData $formData): bool { $file = $this->request->file('photo'); var_dump($file); var_dump($formData); return true; } #[GetMapping(path: 'find/{id}/and/{in}')] #[ApiOperation('查询单体记录')] #[ApiHeader(name: 'test')] public function find(int $id, float $in): array { return ['$id' => $id, '$in' => $in]; } } ``` 验证器 --- [](#验证器) ### 基于框架的验证 [](#基于框架的验证) > 安装hyperf框架验证器[hyperf/validation](https://github.com/hyperf/validation), 并配置(已安装忽略) - 注解 `Required` `Between` `Date` `Email` `Image` `Integer` `Nullable` `Numeric` `Url` `Validation` `...` - 校验生效 > 只需在控制器方法中加上 #\[Valid\] 注解 ``` public function index(#[RequestQuery] #[Valid] DemoQuery $request){} ``` ``` class DemoQuery { #[ApiModelProperty('名称')] #[Required] #[Max(5)] #[In(['qq','aa'])] public string $name; #[ApiModelProperty('正则')] #[Str] #[Regex('/^.+@.+$/i')] #[StartsWith('aa,bb')] #[Max(10)] public string $email; #[ApiModelProperty('数量')] #[Required] #[Integer] #[Between(1,5)] public int $num; } ``` - Validation > rule 支持框架所有验证 - 自定义验证注解 > 只需继承`Hyperf\DTO\Annotation\Validation\BaseValidation`即可 ``` #[Attribute(Attribute::TARGET_PROPERTY)] class Image extends BaseValidation { protected $rule = 'image'; } ``` > 其他例子，请查看example 注意 -- [](#注意) ``` /** * 映射数组. * @var \App\DTO\Address[] */ #[ApiModelProperty('地址')] public array $addressArr; ``` - 控制器中使用了框架`AutoController`注解,只收集了`POST`方法 Swagger界面 --------- [](#swagger界面) [![hMvJnQ](https://camo.githubusercontent.com/bffb31f2d24ce000c5d063e9f2f4ab3b3aa9c6c3a1bcf2a50d44f8def417461e/68747470733a2f2f67697465652e636f6d2f74773636362f736f757263652f7261772f6d61737465722f696d672f737761676765722e706e67)](https://camo.githubusercontent.com/bffb31f2d24ce000c5d063e9f2f4ab3b3aa9c6c3a1bcf2a50d44f8def417461e/68747470733a2f2f67697465652e636f6d2f74773636362f736f757263652f7261772f6d61737465722f696d672f737761676765722e706e67) ### Health Score 27 — LowBetter than 49% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity6 Limited adoption so far Community8 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor1 Top contributor holds 98.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~18 days Total 12 Last Release 1463d ago Major Versions v0.3.0 → v1.0.02021-11-10 v1.0.3 → 2.0.x-dev2022-03-10 v2.0.0-beta1 → v3.0.02022-05-07 ### Community Maintainers ![](https://www.gravatar.com/avatar/c1ec384043dc1c9dc6666c017a0404e06716ece7dbef992047e1c83741c649bc?d=identicon)[wayhood](/maintainers/wayhood) --- Top Contributors [![tw2066](https://avatars.githubusercontent.com/u/24579418?v=4)](https://github.com/tw2066 "tw2066 (72 commits)")[![netyum](https://avatars.githubusercontent.com/u/195082?v=4)](https://github.com/netyum "netyum (1 commits)") --- Tags phpswaggerdocshyperfhyperf swagger ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/wayhood-hyperf-apidocs/health.svg) ``` [![Health](https://phpackages.com/badges/wayhood-hyperf-apidocs/health.svg)](https://phpackages.com/packages/wayhood-hyperf-apidocs) ``` ### Alternatives [tangwei/apidocs A swagger library for Hyperf. 51130.4k8](/packages/tangwei-apidocs)[daodao97/apidog A swagger library for Hyperf. 15040.1k1](/packages/daodao97-apidog)[hyperf/swagger A swagger library for Hyperf. 19338.7k6](/packages/hyperf-swagger)[kakuilan/hyperf-apihelper hyperf api swagger helper 443.0k](/packages/kakuilan-hyperf-apihelper)[clever/clever-php 231.6k](/packages/clever-clever-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)