{"id":14966739,"url":"https://github.com/bestyii/yii2-openapi-reader","last_synced_at":"2025-10-25T17:30:36.153Z","repository":{"id":43576969,"uuid":"243497997","full_name":"bestyii/yii2-openapi-reader","owner":"bestyii","description":"OpenAPI  Specification阅读器，通过对 php 的oas或swagger标准注释文档进行解析，通过swaggerUI渲染成漂亮的API文档","archived":false,"fork":false,"pushed_at":"2024-03-22T13:30:13.000Z","size":29,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-31T09:34:09.539Z","etag":null,"topics":["oas","oas3","openapi","openapi-specification","php-annotation","redoc","swagger","swagger-ui","yii2","yii2-extension","yii2-modules"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bestyii.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-27T10:58:50.000Z","updated_at":"2024-04-12T04:51:07.000Z","dependencies_parsed_at":"2024-09-14T03:31:19.122Z","dependency_job_id":"c6ff0475-d8e4-4bf8-803d-654376e036ac","html_url":"https://github.com/bestyii/yii2-openapi-reader","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.375,"last_synced_commit":"7d57e9299e35aa5fce31d70233c0b6b235e89331"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bestyii%2Fyii2-openapi-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bestyii%2Fyii2-openapi-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bestyii%2Fyii2-openapi-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bestyii%2Fyii2-openapi-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bestyii","download_url":"https://codeload.github.com/bestyii/yii2-openapi-reader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238183668,"owners_count":19430168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oas","oas3","openapi","openapi-specification","php-annotation","redoc","swagger","swagger-ui","yii2","yii2-extension","yii2-modules"],"created_at":"2024-09-24T13:36:52.598Z","updated_at":"2025-10-25T17:30:35.794Z","avatar_url":"https://github.com/bestyii.png","language":"PHP","readme":"Yii2 OpenApi Specification Reader 模块\n============\n原理是采用php的注释来写api文档，注释的语法采用php annotation方式进行解析。\n解析后符合OpenAPI  Specification 规范，可以通过 swagger UI 或 Redoc 进行渲染成可读性强带有交互的api文档。\n\n\n[![Latest Stable Version](https://poser.pugx.org/bestyii/yii2-openapi-reader/v/stable)](https://packagist.org/packages/bestyii/yii2-openapi-reader)\n[![Total Downloads](https://poser.pugx.org/bestyii/yii2-openapi-reader/downloads)](https://packagist.org/packages/bestyii/yii2-openapi-reader)\n[![License](https://poser.pugx.org/bestyii/yii2-openapi-reader/license)](https://packagist.org/packages/bestyii/yii2-openapi-reader)\n\n\nswagger UI\n\n![alt swagger UI](https://static1.smartbear.co/swagger/media/images/tools/opensource/swagger_ui.png?ext=.png \"swagger UI\")\n\nRedoc：\n\n![alt redoc](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png \"redoc\")\n\n这个模块集成了：\n* [swagger-php](https://github.com/zircote/swagger-php) \n* [swagger-ui v3](https://github.com/swagger-api/swagger-ui)\n* [Redocly/redoc](https://github.com/Redocly/redoc)\n\n\n安装 Installation\n------------\n\n通过 [composer](http://getcomposer.org/download/)安装.\n\n项目中直接运行\n\n```\nphp composer.phar require bestyii/yii2-openapi-reader:dev-master\n```\n\n或者添加下面代码到 `composer.json`文件\n\n```\n\"bestyii/yii2-openapi-reader\": \"dev-master\"\n```\n\n\n使用 Usage\n-----\n\nOnce the extension is installed, simply use it in your code by  :\n\nYou set url, where locate json file OR set path for scan\n\n```php\nif (YII_ENV_DEV) {\n $config['modules']['openapireader'] = [\n        'class' =\u003e \\bestyii\\openapiReader\\Module::class,\n        'defaultDoc' =\u003e 'api',\n        'path' =\u003e [\n            'api' =\u003e '@grazio/api',\n            'extensions' =\u003e '@app/extensions',\n        ],\n        // disable page with your logic\n        'isDisable' =\u003e function () {\n            return false;\n        },\n        // replace placeholders in swagger content\n        'afterRender' =\u003e function ($content) {\n            $content = str_replace('{{HOST}}', \\yii\\helpers\\Url::base(true), $content);\n            $content = str_replace('{{BASE_PATH}}', '/api', $content);\n            $content = str_replace('{{SERVER_DESCRIPTION}}', 'description', $content);\n            return $content;\n        }\n    ];\n}\n```\n\n\n现在就可以访问你的API文档了\n\n```\n# swagger 风格\nhttp://yoururl.com/openapireader\n\n# redoc 风格\nhttp://yoururl.com/openapireader/default/redoc\n```\n\n示例 Module\n```php\n\n/**\n * @OA\\OpenApi(\n *     @OA\\Info(\n *         version=\"0.0.1\",\n *         title=\"OpenApi\",\n *         description=\"This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the Bearer `access token` to test the authorization filters.\",\n *     ),\n *     @OA\\Server(\n *         description=\"Test\",\n *         url=\"http://api.bestyii.com/api/\"\n *     ),\n *     @OA\\Server(\n *         description=\"Prod\",\n *         url=\"http://api.bestyii.com/v2/\"\n *     ),\n *     @OA\\ExternalDocumentation(\n *         description=\"更多关于达卡拉的信息\",\n *         url=\"http://bestyii.com\"\n *     )\n * )\n */\n\n/**\n * @OA\\SecurityScheme(\n *   securityScheme=\"bearerAuth\",\n *   type=\"http\",\n *   scheme=\"bearer\",\n *   in=\"header\",\n *   bearerFormat=\"JWT\"\n * )\n * https://swagger.io/docs/specification/authentication/basic-authentication/\n */\n\n```\n\n示例 controller\n```php\n\u003c?php\n\nnamespace app\\modules\\api\\controllers;\n\nuse app\\modules\\api\\models\\UserIdentity;\nuse Yii;\nuse app\\modules\\api\\models\\User;\nuse yii\\data\\ActiveDataProvider;\nuse app\\modules\\api\\components\\ActiveController;\nuse yii\\web\\NotFoundHttpException;\nuse yii\\web\\ServerErrorHttpException;\n\n/**\n * @OA\\Tag(\n *   name=\"Users\",\n *   description=\"用户账号\",\n *   @OA\\ExternalDocumentation(\n *     description=\"更多相关\",\n *     url=\"http://bestyii.com\"\n *   )\n * )\n */\nclass UserController extends ActiveController\n{\n    public $modelClass = 'app\\modules\\api\\models\\UserIdentity';\n\n    /**\n     * @OA\\Get(\n     *     path=\"/users\",\n     *     summary=\"查询 User\",\n     *     tags={\"Users\"},\n     *     description=\"\",\n     *     operationId=\"findUser\",\n     *     @OA\\Parameter(\n     *         name=\"ids\",\n     *         in=\"query\",\n     *         description=\"逗号隔开的 id\",\n     *         required=false,\n     *         @OA\\Schema(\n     *           type=\"integer\",\n     *           @OA\\Items(type=\"int20\"),\n     *         ),\n     *     ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description=\"查询成功\",\n     *         @OA\\Schema(\n     *             type=\"array\",\n     *             @OA\\Items(ref=\"#/components/schemas/User\")\n     *         ),\n     *     ),\n     *     @OA\\Response(\n     *         response=\"400\",\n     *         description=\"无效的id\",\n     *     ),\n     *   security={{\n     *     \"bearerAuth\":{}\n     *   }}\n     * )\n     */\n    public function actionIndex()\n    {\n        $dataProvider = new ActiveDataProvider([\n            'query' =\u003e UserIdentity::find(),\n        ]);\n        return $dataProvider;\n    }\n\n    /**\n     * @OA\\Get(\n     *     path=\"/users/{id}\",\n     *     summary=\"通过ID显示详情\",\n     *     description=\"\",\n     *     operationId=\"getUserById\",\n     *     tags={\"Users\"},\n     *     @OA\\Parameter(\n     *         description=\"id\",\n     *         in=\"path\",\n     *         name=\"id\",\n     *         required=true,\n     *         @OA\\Schema(\n     *           type=\"integer\",\n     *           format=\"int64\"\n     *         )\n     *     ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description=\"操作成功\",\n     *         @OA\\JsonContent(ref=\"#/components/schemas/User\")\n     *     ),\n     *     @OA\\Response(\n     *         response=\"400\",\n     *         description=\"无效的ID\"\n     *     ),\n     *     @OA\\Response(\n     *         response=\"404\",\n     *         description=\"没有找到相应资源\"\n     *     ),\n     *   security={{\n     *     \"bearerAuth\":{}\n     *   }}\n     * )\n     */\n    public function actionView($id)\n    {\n        return $this-\u003efindModel($id);\n    }\n\n    /**\n     * @OA\\Post(\n     *     path=\"/users\",\n     *     tags={\"Users\"},\n     *     operationId=\"addUser\",\n     *     summary=\"添加\",\n     *     description=\"\",\n     *   @OA\\RequestBody(\n     *       required=true,\n     *       description=\"创建 User 对象\",\n     *       @OA\\JsonContent(ref=\"#/components/schemas/User\"),\n     *       @OA\\MediaType(\n     *           mediaType=\"application/x-www-form-urlencoded\",\n     *           @OA\\Schema(\n     *               type=\"object\",\n     *               ref=\"#/components/schemas/User\"\n     *          ),\n     *       )\n     *   ),\n     *     @OA\\Response(\n     *         response=201,\n     *         description=\"操作成功\",\n     *         @OA\\JsonContent(ref=\"#/components/schemas/User\")\n     *     ),\n     *     @OA\\Response(\n     *         response=405,\n     *         description=\"无效的输入\",\n     *     ),\n     *   security={{\n     *     \"bearerAuth\":{}\n     *   }}\n     * )\n     */\n    public function actionCreate()\n    {\n        $model = new UserIdentity();\n        if ($model-\u003eload(Yii::$app-\u003egetRequest()-\u003egetBodyParams(), '') \u0026\u0026 $model-\u003esave()) {\n            $response = Yii::$app-\u003egetResponse();\n            $response-\u003esetStatusCode(201);\n        } elseif (!$model-\u003ehasErrors()) {\n            throw new ServerErrorHttpException('Failed to create the object for unknown reason.');\n        }\n        return $model;\n    }\n\n    /**\n     * @OA\\Put(\n     *     path=\"/users/{id}\",\n     *     tags={\"Users\"},\n     *     operationId=\"updateUserById\",\n     *     summary=\"更新指定ID数据\",\n     *     description=\"\",\n     *     @OA\\Parameter(\n     *         description=\"id\",\n     *         in=\"path\",\n     *         name=\"id\",\n     *         required=true,\n     *         @OA\\Schema(\n     *           type=\"integer\",\n     *           format=\"int64\"\n     *         )\n     *     ),\n     *   @OA\\RequestBody(\n     *       required=true,\n     *       description=\"更新 User 对象\",\n     *       @OA\\JsonContent(ref=\"#/components/schemas/User\"),\n     *       @OA\\MediaType(\n     *           mediaType=\"multipart/form-data\",\n     *           @OA\\Schema(ref=\"#/components/schemas/User\")\n     *       )\n     *   ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description=\"操作成功\",\n     *         @OA\\JsonContent(ref=\"#/components/schemas/User\")\n     *     ),\n     *     @OA\\Response(\n     *         response=400,\n     *         description=\"无效的ID\",\n     *     ),\n     *     @OA\\Response(\n     *         response=404,\n     *         description=\"没有找到相应资源\",\n     *     ),\n     *     @OA\\Response(\n     *         response=405,\n     *         description=\"数据验证异常\",\n     *     ),\n     *   security={{\n     *     \"bearerAuth\":{}\n     *   }}\n     * )\n     */\n    public function actionUpdate($id)\n    {\n        $model = $this-\u003efindModel($id);\n        if ($model-\u003eload(Yii::$app-\u003erequest-\u003egetBodyParams(), '') \u0026\u0026 $model-\u003esave()) {\n            Yii::$app-\u003eresponse-\u003esetStatusCode(200);\n        } elseif (!$model-\u003ehasErrors()) {\n            throw new ServerErrorHttpException('Failed to update the object for unknown reason.');\n        }\n        return $model;\n    }\n\n    /**\n     * @OA\\Delete(\n     *     path=\"/users/{id}\",\n     *     summary=\"删除User\",\n     *     description=\"\",\n     *     operationId=\"deleteUser\",\n     *     tags={\"Users\"},\n     *     @OA\\Parameter(\n     *         description=\"需要删除数据的ID\",\n     *         in=\"path\",\n     *         name=\"id\",\n     *         required=true,\n     *         @OA\\Schema(\n     *             type=\"integer\",\n     *             format=\"int64\"\n     *         )\n     *     ),\n     *     @OA\\Response(\n     *         response=204,\n     *         description=\"没有找到相应资源\"\n     *     ),\n     *     @OA\\Response(\n     *         response=400,\n     *         description=\"无效的ID\"\n     *     ),\n     *     @OA\\Response(\n     *         response=404,\n     *         description=\"没有找到相应资源\"\n     *     ),\n     *   security={{\n     *     \"bearerAuth\":{}\n     *   }}\n     * )\n     */\n    public function actionDelete($id)\n    {\n        $model = $this-\u003efindModel($id);\n        if ($model-\u003esoftDelete() === false) {\n            throw new ServerErrorHttpException('Failed to delete the object for unknown reason.');\n        }\n        Yii::$app-\u003egetResponse()-\u003esetStatusCode(204);\n    }\n\n    /**\n     * Finds the User model based on its primary key value.\n     * If the model is not found, a 404 HTTP exception will be thrown.\n     * @param string $id\n     * @return User the loaded model\n     * @throws NotFoundHttpException if the model cannot be found\n     */\n    protected function findModel($id)\n    {\n        if (($model = UserIdentity::findOne($id)) !== null) {\n            return $model;\n        }\n        throw new NotFoundHttpException('The requested User does not exist.');\n    }\n}\n\n```\n\n示例 model\n```php\n\n/**\n * @OA\\Schema(\n *      schema=\"User\",\n *      required={\"username\"},\n *     @OA\\Property(\n *        property=\"id\",\n *        description=\"User ID\",\n *        type=\"integer\",\n *        format=\"int64\",\n *    ),\n *     @OA\\Property(\n *        property=\"username\",\n *        description=\"用户名\",\n *        type=\"string\",\n *        maxLength=100,\n *    ),\n *     @OA\\Property(\n *        property=\"email\",\n *        description=\"邮箱\",\n *        type=\"string\",\n *        maxLength=100,\n *    ),\n *     @OA\\Property(\n *        property=\"password\",\n *        description=\"密码\",\n *        type=\"string\",\n *        maxLength=64,\n *    ),\n *     @OA\\Property(\n *        property=\"created_at\",\n *        description=\"创建时间\",\n *        type=\"string\",\n *        default=\"0\",\n *    ),\n *     @OA\\Property(\n *        property=\"updated_at\",\n *        description=\"更新时间\",\n *        type=\"string\",\n *        default=\"0\",\n *    ),\n *     @OA\\Property(\n *        property=\"last_login_at\",\n *        description=\"最后登录时间\",\n *        type=\"string\",\n *        default=\"0\",\n *    ),\n *     @OA\\Property(\n *        property=\"ip\",\n *        description=\"登录IP ip2long\",\n *        type=\"integer\",\n *        format=\"int64\",\n *        default=0,\n *    ),\n *)\n */\n```\n\n\n### TODO\n- add cache\n- add customization\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbestyii%2Fyii2-openapi-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbestyii%2Fyii2-openapi-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbestyii%2Fyii2-openapi-reader/lists"}