Laravel5.6整合swagger

Laravel5.6整合swagger

     前面已经写过一篇关于swagger的文章：《Yii+swagger-php生成api文档》，里面记录了swagger的安装以及文档的编写案例，这里再介绍下在laravel下如何整合swagger来使用。

     1、安装swagger

     1）在packagist网站查看与当前laravel版本相匹配的l5-swagger的版本号

 

     2）用compser导入l5-swagger包

     执行命令：composer require "darkaonline/l5-swagger:5.6.*"

     2、生成配置及初始化文件

     1）执行命令

     php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

     2）生成的文件说明

     执行上述命令后，config下面会生成文件l5-swagger.php

     Resources/views下面也会生成vendor文件夹

    

      3、注册swagger

      打开config/app.php，在providers数组中添加：

      \L5Swagger\L5SwaggerServiceProvider::class

     4、添加API相关描述信息及Demo

     在app目录或Controller目录下创建文件：

     这里在app下面创建这两个文件

     1）app/swagger.php 是对api文档和部署环境的简单描述

     2）app/apidoc.php  我们主要是在这里面写注解。swagger会自动扫描这个文件里面的注释来生成api文档

     编写注解遵循的openApi规范，参考文档

     这里有个例子：

     

    5、生成swagger文档的方式

    方式一：手动

    项目下面使用命令行执行：php artisan l5-swagger:generate

    这个每次注释更新之后，都需要执行一次命令来重新生成api文档

    方式二：自动（推荐）

    在.env文件下面配置

    L5_SWAGGER_GENERATE_ALWAYS=true

    配置后，无需手动生成api文档，直接访问api文档地址即可

    6、访问api文档

    访问地址：域名/api/documentation

    host比如下图这里的api.exshare.com：本地配置的域名指向项目public这个路径

 

 

     7、调试使用

 

 

    注意，我执行请求后这里出现了问题：

    

     经过排查，发现问题出在resource/views/index.blade.php中

     

     这个requestInterceptor中的this是有问题的，它指向的是当前windows对象，而我们要的是当前requestInterceptor自身携带的request对象

     其实在github源仓库里面，仔细找找是能发现的，官方已经在最近修复了这个问题，应该是我们在composer拉取这个版本代码时，当时还没有更新，呜呜~~~~~~~~~我太南了！！

     https://github.com/DarkaOnLine/L5-Swagger/issues/304
     https://github.com/DarkaOnLine/L5-Swagger/blob/5.7.3/resources/views/index.blade.php

     

      然后问题处理了，我们这里刷新下swagger文档，重新填参数发起请求，就能看到正确的响应：

   

 

参考链接：

https://packagist.org/

https://xiaoxiami.gitbook.io/swagger/swagger-php-wen-dang/openapi-gui-fan