Laravel集成Swagger使用总结

发表于   |   分类于   |  

刚接触Laravel不久 因为需求想搭建个集成Swagger的开发环境 写下操作过程吧

先放个包的网址 https://packagist.org

之前都是直接在里面搜索swagger 然后又个laterll/swagger使用的人下载次数最多久下载了这个 出了些问题 [可能自己某些步骤错了吧 已经忘记了]。 后来发现了一个包 jlapp/swaggervel 很好用哦 就用这个吧

创建一个Laravel项目

进入自己的本地环境目录

1
composer create-project laravel/laravel swaggertest 5.1.*

对了有时候在linux测试环境下搭建项目的话 要记得查看下 storage目录的读写权限
复制项目下的.env.example文件 重命名为.env 一般创建的时候都会帮你复制过了

上面swaggertest是我的项目名 这个随意 另外Laravel的版本用的是 5.1 的 不知道为什么 每次用5.2的都非常慢，慢到爆炸 用5.1就好很多 难道错觉

进入项目目录 编辑文件composer.json 在最下面加上下面这段代码 增加镜像 以后下载安装什么的可以跑的快点 这一步可以无视不操作 没啥影响

1
2
3
4
5
6
"repositories": {
   "packagist": {
      "type": "composer",
      "url": "https://packagist.phpcomposer.com"
   }
}

集成Swagger

安装包

运行

1
composer require jlapp/swaggervel:dev-master

上面这个swaggervel包有3个版本的 分别是dev-master 2.0.x-dev（这个是给laravel5用的） 1.0.x-dev（这个是给laravel4用的）
会自动帮你安装一些依赖 如果安装成功了在会在 项目根目录下的 vendor下多一个jlapp/swaggervel的文件夹 这里就是swagger的东东了

编辑配置

编辑 config/app.php文件 找到 providers数组在其中添加 如下代码Jlapp\Swaggervel\SwaggervelServiceProvider::class,
网上也有些说要在app/config/app.php文件中添加 但我的项目app文件夹下并没有config文件夹 so就没按照app/config/app.php增加目录创建来编辑

执行php artisan vendor:publish 命令

publish List

这句话就是把刚安装的swaggervel-ui一些东西帮你弄到根目录public目录下
成功的话目录是这样的

vendor List

运行下php artisan route:list 刷新下路由
route List

其实就是把他默认的api/docs 这个路由帮你加进来了
到这里基本已经完成 但是这个时候你去访问你的项目 他可能会报错缺少swg的注释info信息啥的 也并没有生成他运行需要的 json文件
http://localhost/api/docs     [这个是我的项目地址 具体的自己配置吧]

默认情况下他会在 storage/docs这个文件夹下生成所需要的json文件的 因为我们还没有写controller注释 他没有生成json文件 但是把目录已经创建好了

需要注意下vendor/jlapp/swaggervel/src/config/swaggervel.php 这个文件 其中有一个 参数 generateAlways 这个变量 他是控制是否每次都刷新生成json 文件， 推荐在.env中配置一个变量参数设置到这里 这样就不用每次来改这里了 毕竟这个路径找起来挺麻烦的

好了 整个Controller 国际惯例 hello world

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/**
 * @SWG\Swagger(
 *   @SWG\Info(
 *      title="测试类",
 *      version="1.0.0",
 *      description="测试测试"
 *   )
 * )
 */
class TestController extends Controller{
    /**
     * @SWG\Get(
     *      path="/testindex",
     *      tags={"测试相关模块"},
     *      summary="测试输出hello world",
     *      @SWG\Response(
     *          response=200,
     *          description="success",
     *      )
     * )
     */
    public function index(){
        echo "hello world";
    }
}

访问自己配置的域名 看到下面就成功了
swagger success

最后说下 如果只是想搭建微服务架构的话 推荐Lumen哦 速度更快 Laravel默认集成的包还是太多

-------------The End-------------