PHPackages                             timebug/hyperf-apictl - 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. timebug/hyperf-apictl

ActiveLibrary

timebug/hyperf-apictl
=====================

a tool for generating api and doc

v3.1.0(3y ago)01.0k↓100%MITPHPPHP >=8.0

Since Sep 9Pushed 3y ago1 watchersCompare

[ Source](https://github.com/ChuckJack/hyperf-apictl)[ Packagist](https://packagist.org/packages/timebug/hyperf-apictl)[ RSS](/packages/timebug-hyperf-apictl/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (13)Versions (36)Used By (0)

API生成工具
=======

[](#api生成工具)

这个组件主要是通过定义 api 文件来生成代码和API Swagger文档。

默认生成 应用服务层，接口层和领域层。

```
|- app/
    |- Application/  应用层
        |- Service/ 应用服务
            |- Contract/ 应用服务接口。用于依赖注入
    |- Interfaces/ 接口层
        |- Controller/ 接口(控制器)
        |- Desc/ api定义
        |- Types/ 请求体和响应体
    |- Domain/ 领域
        |- Xxx/ 某领域，根据api文件名生成领域名
            |- Service/ 领域服务

```

引入Composer包
-----------

[](#引入composer包)

```
composer require timebug/hyperf-apictl

```

配置
--

[](#配置)

在 `config/autoload` 目录下新建 `apictl.php` 或者通过以下命令生成配置文件

```
php bin/hyperf.php vendor:publish timebug/hyperf-apictl
```

配置主要是定义代码生成的路径

```
return [
    'pool' => 'default',
    'default' => [
        // 应用服务路径
        'service_path' => env('APICTL_SERVICE_PATH', '/app/Application/Service/'),
        // 应用服务接口路径
        'service_contract_path' => env('APICTL_SERVICE_CONTRACT_PATH', '/app/Application/Service/Contract'),
        // 领域路径
        'domain_path' => env('APICTL_DOMAIN_PATH', '/app/Domain'),
        // 控制器路径
        'controller_path' => env('APICTL_CONTROLLER_PATH', '/app/Interfaces/Controller'),
        // 请求响应体路径
        'type_path' => env('APICTL_TYPE_PATH', '/app/Interfaces/Types'),
        // API定义路径
        'api_path' => env('APICTL_API_PATH', '/app/Interfaces/Desc'),
        // API文档路径
        'swagger_name' => env('APICTL_SWAAGER_NAME', 'api.swaager.json'),
        // API文档请求头参数, 没有可不填
        'api_common_headers' => [
            [
                "name" => "appid",
                "in" => "header",
                "description" => "应用ID",
                "required" => true,
                "example" => "{{appid}}",
                "schema" => ["type" => "string"]
            ],
            [
                "name" => "nonce",
                "in" => "header",
                "description" => "随机字符串",
                "required" => true,
                "example" => "{{nonce}}",
                "schema" => ["type" => "string"]
            ],
            [
                "name" => "timestamp",
                "in" => "header",
                "description" => "当时时间戳",
                "required" => true,
                "example" => "{{timestamp}}",
                "schema" => ["type" => "integer"]
            ],
            [
                "name" => "signature",
                "in" => "header",
                "description" => "请求签名",
                "required" => true,
                "example" => "{{signature}}",
                "schema" => ["type" => "string"]
            ]
        ]
    ],
];
```

定义API文件
-------

[](#定义api文件)

在 `app/Interfaces/Desc` 新建一个 api 文件，在 PHPStorm 的IDE可以安装 `goctl` 插件来支持api语法。

这里新建 `cate.api` 文件

```
type (
    ListCateItem {
        id      int    `json:"id" desc:"类目ID"`
        title   string `json:"title" desc:"标题"`
        sort    int    `json:"sort" desc:"排序"`
        state   int    `json:"state" desc:"状态.1：启用;0：禁用."`
        addTime int    `json:"add_time" desc:"添加时间"`
    }
    ListCateReq {
        page   int   `json:"page" default:"1" desc:"页码"`
        size   int   `json:"size,optional" default:"10" desc:"页面大小"`
    }
    ListCateResp {
        total     int            `json:"total" desc:"总条数"`
        totalPage int            `json:"total_page" desc:"总页数"`
        size      int            `json:"size" desc:"当前页结果数量"`
        items     []ListCateItem `json:"items" desc:"类目"`
    }
)

@server(
    prefix: /v1/cate
    group: cate
)
service cate {

    @doc "类目列表"
    @handler lists
    get /lists (ListCateReq) returns (ListCateResp)
}

```

- [API 语法请参考](https://legacy.go-zero.dev/cn/api-grammar.html)

说明:

- 字段名(小驼峰): 字段名会是请求体或者响应体的属性名
- json: 注释里的json是映射字段，也就是实际请求或者响应对应的字段
- optional: 表明这个字段不是必要参数
- default: 定义默认值
- desc: 注释
- prefix: 这是会生成路由前缀

**注意:由于`json:"test" desc:"测试"`这里是通过空格进行分组，所以在desc中请不要出现空格，以及`:`，否则会出现格式错误**

生成API代码
=======

[](#生成api代码)

```
# php bin/hyperf.php apictl:api --api=cate.api

create /var/www/code/app/Interfaces/Controller/CateController.php successfully.
create /var/www/code/app/Domain/Cate/Service/ListCateDomainService.php successfully.
create /var/www/code/app/Interfaces/Types/Cate/ListCateReq.php successfully.
create /var/www/code/app/Interfaces/Types/Cate/ListCateResp.php successfully.
create /var/www/code/app/Interfaces/Types/Cate/ListCateItem.php successfully.
create /var/www/code/app/Application/Service/CateService.php successfully.
create /var/www/code/app/Application/Service/Contract/CateServiceInterface.php successfully.

```

这里会生成以下文件

### 请求体和响应体

[](#请求体和响应体)

- `app/Interfaces/Types/Cate/ListCateReq.php`

```