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 "L5SwaggerL5SwaggerServiceProvider"

3）生成的文件说明

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

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

 

3、注册swagger

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

L5SwaggerL5SwaggerServiceProvider::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