PHPackages                             david-wang/apinote - 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. david-wang/apinote

ActiveLibrary[API Development](/categories/api)

david-wang/apinote
==================

A swagger library for Hyperf.

v1.0(4y ago)010MITJavaScriptPHP >=7.2

Since May 1Pushed 4y ago1 watchersCompare

[ Source](https://github.com/DavidWang666/apinote)[ Packagist](https://packagist.org/packages/david-wang/apinote)[ RSS](/packages/david-wang-apinote/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (9)Versions (2)Used By (0)

Api Note
--------

[](#api-note)

一个 [Hyperf](https://github.com/hyperf/hyperf) 框架的 Api 参数校验及 swagger 文档生成组件

1. 根据注解自动进行Api参数的校验, 业务代码更纯粹.
2. 根据注解自动生成Swagger文档, 让接口文档维护更省心.

安装
--

[](#安装)

```
composer require david-wang/apinote

```

使用
--

[](#使用)

#### 1. 发布配置文件

[](#1-发布配置文件)

```
php bin/hyperf.php vendor:publish DavidWang/apinote

# hyperf/validation 的依赖发布

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

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

# 视图发布
php bin/hyperf.php vendor:publish hyperf/view-engine
```

### 2. 修改配置文件

[](#2-修改配置文件)

根据需求修改 `config/autoload/apinote.php`

### 3. 启用 Api参数校验中间件

[](#3-启用-api参数校验中间件)

```
// config/autoload/middlewares.php

DavidWang\ApiNote\Middleware\ApiValidationMiddleware::class;
```

### 4. 校验规则的定义

[](#4-校验规则的定义)

规则列表参见 [hyperf/validation 文档](https://hyperf.wiki/#/zh-cn/validation?id=%e9%aa%8c%e8%af%81%e8%a7%84%e5%88%99)

更详细的规则支持列表可以参考 [laravel/validation 文档](https://learnku.com/docs/laravel/6.x/validation/5144#c58a91)

扩展在原生的基础上进行了封装, 支持方便的进行 `自定义校验` 和 `控制器回调校验`

实现思路
----

[](#实现思路)

api参数的自动校验: 通过中间件拦截 http 请求, 根据注解中的参数定义, 通过 `valiation` 自动验证和过滤, 如果验证失败, 则拦截请求. 其中`valiation` 包含 规则校验, 参数过滤, 自定义校验 三部分.

swagger文档生成: 在`php bin/hyperf.php start` 启动 `http-server` 时, 通过监听 `BootAppConfListener` 事件, 扫码控制器注解, 通过注解中的 访问类型, 参数格式, 返回类型 等, 自动组装 `swagger.json` 结构, 最后输出到 `config/autoload/apinote.php` 定义的文件路径中

支持的注解
-----

[](#支持的注解)

#### Api类型

[](#api类型)

`GetApi`, `PostApi`, `PutApi`, `DeleteApi`

### 参数类型

[](#参数类型)

`Header`, `Quyer`, `Body`, `FormData`, `Path`

### 其他

[](#其他)

`ApiController`, `ApiResponse`, `ApiVersion`, `ApiServer`, `ApiDefinitions`, `ApiDefinition`

```
/**
 * @ApiVersion(version="v1")
 * @ApiServer(name="http")
 */
class UserController {}
```

`ApiServer` 当你在 `config/autoload.php/server.php servers` 中配置了多个 `http` 服务时, 如果想不同服务生成不同的`swagger.json` 可以在控制器中增加此注解.

`ApiVersion` 当你的统一个接口存在不同版本时, 可以使用此注解, 路由注册时会为每个木有增加版本号, 如上方代码注册的实际路由为 `/v1/user/***`

`ApiDefinition` 定义一个 `Definition`，用于Response的复用。 *swagger* 的difinition是以引用的方式来嵌套的，如果需要嵌套另外一个(值为object类型就需要嵌套了) ，可以指定具体 `properties` 中的 `$ref` 属性

`ApiDefinitions` 定义一个组`Definition`

`ApiResponse` 响应体的`schema`支持为key设置简介. `$ref` 属性可以引用 `ApiDefinition` 定义好的结构(该属性优先级最高)

```
@ApiResponse(code="0", description="删除成功", schema={"id|这里是ID":1})
@ApiResponse(code="0", description="删除成功", schema={"$ref": "ExampleResponse"})
```

具体使用方式参见下方样例

样例
--

[](#样例)

```