README

Laravel 开发工具箱中的 SwaggerNotes 生成工具

注意：此工具仅生成注释内容，需要依赖 swagger-php 包才能生成 .yaml 接口文件

1. 本地开发环境安装依赖包

   composer require laravel-toolbox/swagger-notes --dev

2. 请在 Controller 类中对应的方法 return 前，加入如下代码：

   \Toolbox\Facades\SwaggerNotes::setRequest($request)
            ->setResponse($this->jsonRender(TransformHelper::camelSnakeCase($result, 'camel_case')))
            ->setComments(['affilliate_web', 'affilliate', 'member'], $request->rules($this->affiliateService), $this->optionComments)
            ->setApiInfo([
                'summary' => '查詢大聯盟會員資料',
                'description' => '含是否填寫個人資料、賬戶資料',
                'operation_id' => __FUNCTION__,
                'tags' => __CLASS__,
            ])
            ->generate();

3. 添加支持扩展字段的注释信息，在调用类中新增和修改如下代码即可：

   public $optionComments = [
        'metadata' => '元數據',
        'data' => '數據',
        'desc' => '狀態描述',
        'infoType' => '資料類型：ALL-全部;PROFILE-個人資料;ADDRINFO-通訊資料;ACCINFO-帳戶資料;WEBINFO-網站資料;',
        'profile' => '個人資料',
        'addrInfo' => '通訊資料',
        'accInfo' => '帳戶資料',
        'webInfo' => '網站資料',
        'brandName' => '白牌名稱',
        'brandSetting' => '白牌設置',
        'imageUrl' => '圖片連結',
        'brandUrl' => '白牌連結',
        'footerCopyright' => '底部授權信息',
        'citys' => '所含城市',
        'prods' => '所含省份',
        'profileFinished' => '個人資料是否完成的標識',
        'accInfoFinished' => '賬戶資料是否完成的標識',
        'isApproved' => '聯盟審核是否通過的標識',
        'isActive' => '聯盟賬戶是否活躍的標識',
    ];

4. 默认生成路径在swagger/SwaggerNotes目录下，层级结构如下：

   swagger
   ├── Swagger                        # 生成的注釋目錄
   │     ├── Affiliate                # 生成的接口目錄
   │     │      └── affiliateView.php # 生成的接口注釋文件
   │     └── swagger.php              # 生成的注釋頭部信息文件
   ├── swagger-constants.php
   ├── swagger-info.php
   ├── swagger.yaml
   └── swagger_doc.yaml               # 生成的接口文件

5. 附表