diff --git a/README.md b/README.md index 63a7b50..a203470 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ ## 🤷‍♀️ Apidoc是什么？ -Apidoc是一个通过解析注解生成Api接口文档的PHP composer扩展，兼容Laravel、ThinkPHP、Hyperf、Webman等框架； +Apidoc是一个通过解析注解生成Api接口文档的PHP composer扩展，兼容Laravel、ThinkPHP、Hyperf、Webman、Yii 等框架； 全面的注解引用、数据表字段引用，简单的注解即可生成Api文档，而Apidoc不仅于接口文档，在线接口调试、Mock调试数据、调试事件处理、Json/TypeScript生成、接口生成器、代码生成器等诸多实用功能，致力于提高Api接口开发效率。 @@ -51,6 +51,7 @@ Apidoc是一个通过解析注解生成Api接口文档的PHP composer扩展， |Laravel|8.x、9.x、10.x| |Webman|1.x| |Hyperf|2.x、3.x| +|Yii|2.x| ## 📖使用文档 diff --git a/src/controllers/Yii2Controller.php b/src/controllers/Yii2Controller.php new file mode 100644 index 0000000..a861c20 --- /dev/null +++ b/src/controllers/Yii2Controller.php @@ -0,0 +1,148 @@ + ContentNegotiator::class, + 'formats' => [ + 'application/json' => Response::FORMAT_JSON + ] + ]; + + return $behaviors; + } + + public function init($checkAuth = false) + { + $this->_ctrl = new Controller(); + $this->_ctrl->init(); + + //给接口响应结果绑定beforeSend事件 + Yii::$app->getResponse()->on(Response::EVENT_BEFORE_SEND, [$this, 'beforeSend']); + } + + /** + * @param Event $event + */ + public function beforeSend(Event $event) + { + /* @var $response yii\web\Response */ + $response = $event->sender; + + //针对Yii2框架404默认返回的是html页面，rest没处理 + if ($response->statusCode === 404){ + $response->format = Response::FORMAT_JSON; + $response->data = [ + 'name' => $response->statusText, + 'message' => '请求不存在', + 'code' => 0, + 'status' => 404, + ]; + } + } + + /** + * 获取配置 + */ + public function actionConfig() + { + return $this->_ctrl->getConfig(); + } + + /** + * 获取api文档菜单 + */ + public function actionApiMenus() + { + return $this->_ctrl->getApiMenus(); + } + + /** + * 获取接口明细 + * @return array + */ + public function actionApiDetail() + { + return $this->_ctrl->getApiDetail(); + } + + public function actionDocMenus() + { + return $this->_ctrl->getMdMenus(); + } + + public function actionDocDetail() + { + return $this->_ctrl->getMdDetail(); + } + + public function actionVerifyAuth() + { + return $this->_ctrl->verifyAuth(); + } + + public function actionGenerator() + { + return $this->_ctrl->createGenerator(); + } + + public function actionCancelAllCache() + { + return $this->_ctrl->cancelAllCache(); + } + + public function actionCreateAllCache() + { + return $this->_ctrl->createAllCache(); + } + + public function actionRenderCodeTemplate() + { + return $this->_ctrl->renderCodeTemplate(); + } + + public function actionAllApiMenus() + { + return $this->_ctrl->getAllApiMenus(); + } + + public function actionAddApiShare() + { + return $this->_ctrl->addApiShare(); + } + + public function actionGetApiShareList() + { + return $this->_ctrl->getApiShareList(); + } + + public function actionGetApiShareDetail() + { + return $this->_ctrl->getApiShareDetail(); + } + + public function actionDeleteApiShare() + { + return $this->_ctrl->deleteApiShare(); + } + + public function actionHandleApiShareAction() + { + return $this->_ctrl->handleApiShareAction(); + } +} \ No newline at end of file diff --git a/src/docs/yii2_install.md b/src/docs/yii2_install.md new file mode 100644 index 0000000..5dc1a35 --- /dev/null +++ b/src/docs/yii2_install.md @@ -0,0 +1,83 @@ +# Yii2 安装 + +> 在安装本插件时，确保你已成功安装 Yii2 的项目的 advanced 模板，并成功运行 +安装方法参考：[Yii2 文档](https://learnku.com/docs/yii-framework/2.0.x/advanced-install/11993) + +## 1、安装插件 + +进入项目根目录，执行如下命令： + +```shell +composer require hg/apidoc +``` + +## 2、配置文件 + +1、手动添加apidoc.php配置文件 + +手动将 `/vendor/hg/apidoc/src/config.php` 拷贝到`{app}/config/`目录下，并重命名为`apidoc.php` + + +2、Yii 2.x 版本需手动配置，让 Apidoc 在应用初始化时注册相关服务，如下： + +```php +// {app}/config/main.php 中 +return [ + // 增加 apidoc + 'bootstrap' => ['log', 'apidoc'], + // 组件中 + 'components' => [ + 'apidoc' => [ + 'class' => '\hg\apidoc\providers\Yii2Service', + 'cfgPath' => __DIR__ . '/apidoc.php' + ], + // 如果要支持国际化 + 'i18n' => [ + 'translations' => [ + '*' => [ + 'class' => 'yii\i18n\PhpMessageSource', + // {app}/messages/en-US/apidoc.php 英文 + // {app}/messages/zh-CN/apidoc.php 中文 + 'basePath' => '@app/messages', + 'sourceLanguage' => 'en-US', + 'fileMap' => [ + 'apidoc' => 'apidoc.php' + ], + ], + ], + ], + ], + // 如果要支持国际化 + 'sourceLanguage' => 'en-US',//源语言 + 'language' => 'zh-CN',//目标语言 +]; + +// {app}/messages/en-US/apidoc.php 中 + 'Test', +]; +``` + +> 根据项目结构调整 apps 配置 +```php +// {app}/config/apidoc.php +'apps' => [ + [ + 'title'=>'Api接口', + // （注意）核对配置文件中此目录是否正确 + 'path'=>'modules\v1\controllers', + 'key'=>'api', + ] +], +``` + +## 3、添加前端页面 + + + + +下载完成后解压，将apidoc文件夹拷贝到你的项目 web 目录下 + +打开浏览器访问 [http://你的域名/apidoc/](http://你的域名/apidoc/) ，出现接口文档页面，表示安装成功。 \ No newline at end of file diff --git a/src/providers/Yii2Service.php b/src/providers/Yii2Service.php new file mode 100644 index 0000000..e301798 --- /dev/null +++ b/src/providers/Yii2Service.php @@ -0,0 +1,106 @@ +cfgPath; + + Yii::$app->controllerMap = [ + 'apidoc' => [ + 'class' => '\hg\apidoc\controllers\Yii2Controller', + 'enableCsrfValidation' => false, + ], + ]; + + $this->initConfig(); + self::registerApidocRoutes(); + } + + /** + * @inheritdoc + * @return array|mixed + */ + static function getApidocConfig() + { + $config = require self::$_cfg_path ?: __DIR__ . '/../config.php'; + + if (!(!empty($config['auto_url']) && !empty($config['auto_url']['filter_keys']))){ + $config['auto_url']['filter_keys'] = ['app','controller']; + } + $config['app_frame'] = "yii2"; + return $config; + } + + /** + * @inheritdoc + * @throws InvalidConfigException + */ + static function registerRoute($route) + { + $rule_key = mb_substr($route['uri'], 1); + $rule_val = Inflector::camel2id($rule_key); + $url_manager = Yii::$app->urlManager; + $url_manager->rules[$rule_key] = $rule_val; + $url_manager->init(); + } + + /** + * @throws Exception + */ + static function databaseQuery($sql) + { + Yii::$app->db->createCommand($sql)->execute(); + } + + static function getRootPath() + { + //dd(Yii::getAlias('@app')); + return Yii::getAlias('@app') . DIRECTORY_SEPARATOR; + } + + static function getRuntimePath() + { + return Yii::getAlias('@runtime'); + } + + static function setLang($locale) + { + Yii::$app->language = $locale; + } + + static function getLang($lang) + { + return Yii::t('apidoc', mb_substr($lang, mb_strlen('apidoc.'))); + } + + static function handleResponseJson($res) + { + return $res; + } + + static function getTablePrefix() + { + return Yii::$app->db->tablePrefix; + } +} \ No newline at end of file