{"id":18704771,"url":"https://github.com/lancewan/laravel5-swagger","last_synced_at":"2025-04-12T09:33:16.054Z","repository":{"id":56994946,"uuid":"60395011","full_name":"lanceWan/laravel5-swagger","owner":"lanceWan","description":"基于 slampenny/Swaggervel 实现的 swagger API文档，更新 swagger UI 到最新版本，支持多语言设置。","archived":false,"fork":false,"pushed_at":"2016-06-04T09:27:05.000Z","size":1019,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-18T21:21:44.001Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanceWan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-04T05:33:49.000Z","updated_at":"2021-12-17T18:27:31.000Z","dependencies_parsed_at":"2022-08-21T13:50:38.921Z","dependency_job_id":null,"html_url":"https://github.com/lanceWan/laravel5-swagger","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanceWan%2Flaravel5-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanceWan%2Flaravel5-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanceWan%2Flaravel5-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanceWan%2Flaravel5-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanceWan","download_url":"https://codeload.github.com/lanceWan/laravel5-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223510320,"owners_count":17157306,"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":[],"created_at":"2024-11-07T12:08:17.859Z","updated_at":"2024-11-07T12:08:18.440Z","avatar_url":"https://github.com/lanceWan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# laravel5-swagger\n\n基于 [slampenny/Swaggervel](https://github.com/slampenny/Swaggervel) 实现的 [swagger](http://swagger.io/) API文档，更新 swagger UI 到最新版本，支持多语言设置。\n\n# Swagger 2\n\n本扩展使用的是 Swagger UI 2.1.4 版本\n\n# OAuth2\n\n关于 OAuth2 的现在还未测试使用，后期会进行测试更新。。。\n\n# 安装\n\n* 在项目根目录下执行： `composer require iwanli/laravel5-swagger` 或在 `composer.json` 中添加 `\"iwanli/laravel5-swagger\": \"~0.1\"` 然后执行 `composer update`\n* 添加 `Iwanli\\Swagger\\SwaggerServiceProvider::class` 到 `app/config/app.php` providers 数组中\n* 最后执行 `php artisan vendor:publish`\n\n**默认的访问路由**\n\n1. json格式访问地址：www.example.com/docs\n2. swagger UI 访问地址：www.example.com/api/docs\n\n# 配置文件\n\n在执行 `php artisan vendor:publish` 成功后，会生成 `config/swagger.php` 的配置文件，配置文件内容如下：\n\n```php\n\u003c?php\nreturn [\n    /*\n      |--------------------------------------------------------------------------\n      | 多语言配置\n      | 可选语言：en、es、fr、it、ja、pl、pt、ru、tr、zh-cn\n      |--------------------------------------------------------------------------\n    */\n    'lang' =\u003e 'zh-cn',\n    /*\n      |--------------------------------------------------------------------------\n      | 注释文档存放位置\n      |--------------------------------------------------------------------------\n    */\n    'doc-dir' =\u003e storage_path() . '/docs',\n    /*\n      |--------------------------------------------------------------------------\n      | 文档路由\n      |--------------------------------------------------------------------------\n    */\n    'doc-route' =\u003e 'docs',\n    /*\n      |--------------------------------------------------------------------------\n      | UI界面路由\n      |--------------------------------------------------------------------------\n    */\n    'api-docs-route' =\u003e 'api/docs',\n    /*\n      |--------------------------------------------------------------------------\n      | 监听目录\n      |--------------------------------------------------------------------------\n    */\n    \"app-dir\" =\u003e \"app\",\n\n\t......\n\n```\n\n这里我默认是中文的，大部分情况下，大家可以不用修改配置，默认即可。\n\n# 简单的使用\n\n## 控制器中使用\n\n```\n\u003c?php\n...\n/**\n * @SWG\\Swagger(\n *     schemes={\"http\"},\n *     host=\"itest.me/\",\n *     @SWG\\Info(\n *         version=\"1.0.0\",\n *         title=\"Swagger Petstore\",\n *         description=\"This is a sample server Petstore server.  You can find out more about Swagger at \u003ca href=\"\"http://swagger.io\"\"\u003ehttp://swagger.io\u003c/a\u003e or on irc.freenode.net, #swagger.  For this sample, you can use the api key \"\"special-key\"\" to test the authorization filters\",\n *         termsOfService=\"http://helloreverb.com/terms/\",\n *     ),\n *     @SWG\\ExternalDocumentation(\n *         description=\"Find out more about Swagger\",\n *         url=\"http://swagger.io\"\n *     )\n * )\n */\nclass SimplePetsController\n{\n    /**\n     * @SWG\\Get(\n     *     path=\"/pets\",\n     *     description=\"Returns all pets from the system that the user has access to\",\n     *     operationId=\"findPets\",\n     *     produces={\"application/json\", \"application/xml\", \"text/xml\", \"text/html\"},\n     *     @SWG\\Parameter(\n     *         name=\"tags\",\n     *         in=\"query\",\n     *         description=\"tags to filter by\",\n     *         required=false,\n     *         type=\"array\",\n     *         @SWG\\Items(type=\"string\"),\n     *         collectionFormat=\"csv\"\n     *     ),\n     *     @SWG\\Parameter(\n     *         name=\"limit\",\n     *         in=\"query\",\n     *         description=\"maximum number of results to return\",\n     *         required=false,\n     *         type=\"integer\",\n     *         format=\"int32\"\n     *     ),\n     *     @SWG\\Response(\n     *         response=200,\n     *         description=\"pet response\",\n     *         @SWG\\Schema(\n     *             type=\"array\",\n     *             @SWG\\Items(ref=\"#/definitions/pet\")\n     *         ),\n     *     ),\n     *     @SWG\\Response(\n     *         response=\"default\",\n     *         description=\"unexpected error\",\n     *         @SWG\\Schema(\n     *             ref=\"#/definitions/errorModel\"\n     *         )\n     *     )\n     * )\n     */\n    public function findPets()\n    {\n    }\n    /**\n     * @SWG\\Get(\n     *     path=\"/pets/{id}\",\n     *     description=\"Returns a user based on a single ID, if the user does not have access to the pet\",\n     *     operationId=\"findPetById\",\n     *     @SWG\\Parameter(\n     *         description=\"ID of pet to fetch\",\n     *         format=\"int64\",\n     *         in=\"path\",\n     *         name=\"id\",\n     *         required=true,\n     *         type=\"integer\"\n     *     ),\n     *     produces={\n     *         \"application/json\",\n     *         \"application/xml\",\n     *         \"text/html\",\n     *         \"text/xml\"\n     *     },\n     *     @SWG\\Response(\n     *         response=200,\n     *         description=\"pet response\",\n     *         @SWG\\Schema(ref=\"#/definitions/pet\")\n     *     ),\n     *     @SWG\\Response(\n     *         response=\"default\",\n     *         description=\"unexpected error\",\n     *         @SWG\\Schema(ref=\"#/definitions/errorModel\")\n     *     )\n     * )\n     */\n    public function findPetById()\n    {\n    }\n    /**\n     * @SWG\\Post(\n     *     path=\"/pets\",\n     *     operationId=\"addPet\",\n     *     description=\"Creates a new pet in the store.  Duplicates are allowed\",\n     *     produces={\"application/json\"},\n     *     @SWG\\Parameter(\n     *         name=\"pet\",\n     *         in=\"body\",\n     *         description=\"Pet to add to the store\",\n     *         required=true,\n     *         @SWG\\Schema(ref=\"#/definitions/petInput\"),\n     *     ),\n     *     @SWG\\Response(\n     *         response=200,\n     *         description=\"pet response\",\n     *         @SWG\\Schema(ref=\"#/definitions/pet\")\n     *     ),\n     *     @SWG\\Response(\n     *         response=\"default\",\n     *         description=\"unexpected error\",\n     *         @SWG\\Schema(ref=\"#/definitions/errorModel\")\n     *     )\n     * )\n     * @SWG\\Definition(\n     *     definition=\"petInput\",\n     *     allOf={\n     *         @SWG\\Schema(ref=\"pet\"),\n     *         @SWG\\Schema(\n     *             required={\"name\"},\n     *             @SWG\\Property(\n     *                 property=\"id\",\n     *                 type=\"integer\",\n     *                 format=\"int64\"\n     *             )\n     *         )\n     *     }\n     * )\n     */\n    public function addPet()\n    {\n    }\n    /**\n     * @SWG\\Delete(\n     *     path=\"/pets/{id}\",\n     *     description=\"deletes a single pet based on the ID supplied\",\n     *     operationId=\"deletePet\",\n     *     @SWG\\Parameter(\n     *         description=\"ID of pet to delete\",\n     *         format=\"int64\",\n     *         in=\"path\",\n     *         name=\"id\",\n     *         required=true,\n     *         type=\"integer\"\n     *     ),\n     *     @SWG\\Response(\n     *         response=204,\n     *         description=\"pet deleted\"\n     *     ),\n     *     @SWG\\Response(\n     *         response=\"default\",\n     *         description=\"unexpected error\",\n     *         @SWG\\Schema(ref=\"#/definitions/errorModel\")\n     *     )\n     * )\n     */\n    public function deletePet()\n    {\n    }\n}\n```\n\n## 模型中使用\n\n```\n\u003c?php\n...\n\n/**\n * @SWG\\Definition(definition=\"pet\", required={\"id\", \"name\"})\n */\nclass SimplePet\n{\n    /**\n     * @SWG\\Property(format=\"int64\")\n     * @var int\n     */\n    public $id;\n    /**\n     * @SWG\\Property()\n     * @var string\n     */\n    public $name;\n    /**\n     * @var string\n     * @SWG\\Property()\n     */\n    public $tag;\n}\n```\n\n本扩展会自动监听app目录下面的所有控制器(controller)和模型(model)注释张带有@SWG的标签并解析，这里的示例我只是简单的先贴上别人的代码，后期我会将这些命令和界面全部放在个人的阿里云上，方便大家学习。\n\n\u003e 另外我在扩展里目录添加了一个 `Examples` 目录，大家可以参照这个例子，动动手在本地试试，网上的预览地址：[http://petstore.swagger.io/](http://petstore.swagger.io/) ，关于更多的参数命令：[http://swagger.io/specification/](http://swagger.io/specification/) ，本人也在深入研究中。大家可以互相交流讨论。\n\n如果有上面错误或bug，欢迎反馈~ 创建一个 [Issues](https://github.com/lanceWan/laravel5-swagger/issues) 或邮件反馈 `709344897@qq.com`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flancewan%2Flaravel5-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flancewan%2Flaravel5-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flancewan%2Flaravel5-swagger/lists"}