Lumen集成Swagger使用总结

最近想用Lumen搭建一个微服务项目主要给别的项目提供API接口准备用swagger做显示和调试结果试了几次因为各种原因都失败了，一波三折最后还好成功了写个记录吧

Lumen:

Laravel中衍生出的框架为速度而生，相对Laravel而言它更适合做微服务架构和API开发

Swagger:

可以方便美观的呈现出接口API的各种定义，生成API文档，包括参数路径啥的，有时后端修改了API参数或者其他设置直接通过这个swagger的ui就可以看了方便测试调试等等

准备工作

1. 确保PHP版本 >5.5.9
2. OpenSSL PHP Extension
3. 确保已经安装 Composer 并配置到环境变量中

创建一个Lumen项目

1	composer create-project laravel/lumen --prefer-dist lumen-swagger "5.1.*"

其中 lumen-swagger是项目名可以随便起一个自己喜欢的名字

安装好后进入 lumen-swagger 目录复制其中的.env.example 重命名为.env文件
修改.env这个文件中的参数
APP_KEY=P5B4DQdsKGVjczjdnTTiJBzj90ZJBh2F
这个值需要32位的一个随机字符串你可以不用使用我上面这个，先暂时用下
等程序可以跑起来可以自己写个随机生成的随机function 去生成在替换掉好了 0-9 a-z A-Z 【这个东东加密用的安全作用吧】

注意Lumen里好多artisan命令都用不了不然我也想直接用php artisan key:generate 来生成这个key了
使用php artisan list可以看到当前的lumen框架中支持的artisan命令

下一步修改 bootstap/app.php文件把下面这个注释去掉

<?php
	require_once __DIR__.'/../vendor/autoload.php';
	//（这里下面这行原本是注释掉的）打开这里告诉lumen通过 .env配置文件来设置
	Dotenv::load(__DIR__.'/../');

然后lumen就算安装完成了你可以自己配置虚拟主机啦之类的来访问测试或者使用
php artisan sreve --port=8888
这个命令就是启动一个server，上面的artisan列表里也有【ps:这个端口号你随便设置别和你已经在用的冲突好了】
当你看到下面的提示就说明启动成功了哦
Lumen development server started on http://localhost:8888/
这时你访问浏览器输入 http://localhost:8888/

看到这个就算Lumen安装完成了

集成 Swagger

可以去 https://packagist.org 去找下 Swagger相关的包这里直接推荐 darkaonline/swagger-lume 这个包
贴个作者项目地址： https://github.com/DarkaOnLine/SwaggerLume (感谢下)

一、安装

1	composer require "darkaonline/swagger-lume 1.*"

二、修改配置

安装完成后编辑 bootstrap/app.php 文件在大概 26 行处添加如下内容

//注册门面
$app->withFacades();
//配置swagger的config文件
$app->configure('swagger-lume');
//注册swagger到服务容器
$app->register(\SwaggerLume\ServiceProvider::class);

三、生成文件

运行 php artisan swagger-lume:publish-config 生成配置文件如果成功的话你会看到你的项目目录下多了一个config文件夹并且下面有一个swagger-lume.php的配置文件这个文件里的配置就是swagger运行需要的配置参数
运行 php artisan swagger-lume:publish 它会帮你把以前swagger前端显示的一些UI啦配置文件什么帮你统统搞定如果成功的话你会发现在你项目的根目录下的 public 和resource 文件夹下多了一个 vendor/swagger-lume的文件夹
运行 php artisan swagger-lume:generate 这个是帮助你生成swagger运行锁需要的一个json文件这一步可以先不操作因为我们还没有写API的Controller以及Swagger的标签运行的话会报错 Required @SWG\Info() not found类似这样一个错误这是正常的哦
同时我们可以看到在 storage目录下多了一个api-docs的文件夹（swagger运行需要的json文件就是存放在这里的）虽然他是空的看到这个说明刚刚那个命令有效等我们写完测试Controller就生成了

进入目录 app/Http/Controllers 下新建一个TestController.php （这个随便你了哦）
国际惯例 hello world

<?php
    namespace App\Http\Controllers;
    use App\Http\Controllers\Controller;
    use Illuminate\Http\Request;
    /**
     * @SWG\Swagger(
     *   @SWG\Info(
     *      title="测试类",
     *      version="1.0.0",
     *      description="测试测试"
     *   )
     * )
     */
    class TestController extends Controller{
        /**
         * @SWG\Get(
         *      path="/testindex",
         *      tags={"测试相关模块"},
         *      summary="测试输出hello world",
         *      @SWG\Parameter(
         *       name="say",
         *       required=true,
         *       in="query",
         *       type="string",
         *       description="传递的参数"
         *   ),
         *      @SWG\Response(
         *          response=200,
         *          description="success",
         *      )
         * )
         */
        public function index(Request $request){
            echo "hello ".$request->get('say');
        }
    }

写完TestController记得去route.php 中去添加路由
$app->get('/testindex','TestController@index');
路由你可以随便定的不一定我写的这个

注意：上面的index()方法上面的swagger标签中的path参数那个斜线 /一定要带上，像这样 path="/testindex" 不然它会很傻的在你访问的时候也没有，那你的请求就变成这样了
http://localhost:8888testindex?say=d
而你原意想请求的地址是http://localhost:8888/testindex?say=d

四、修改Swagger配置文件

swagger 的配置文件 config/swagger-lume.php

'routes' => [
        //这个是swagger的默认路由 输入我们自己配置的地址拼上这个就可以访问了
        //不喜欢的可以改 我比较习惯用 api-docs 随便改 如果用上面的8888server的话
        //访问地址就是 http://localhost:8888/api/documentation
        'api' => 'api/documentation',
        //这个就是访问json文件的路由
        'docs' => 'docs',
    ],
    ........[此处分割 N 行]
    //这个参数是设置swagger是否每次都检测重新生成json文件 如果为true的话访问速度会有点慢
    //可以在新加api功能的时候设为true把接口列表加载出来后设为false下次就不用重新生成了
    //另外如果不想改这里可以设置一个配置参数放到.env里（好像区别不大，总要改一个地方 ）
    'generate_always' => env('SWAGGER_GENERATE_ALWAYS', true),