Laravel5.5中集成Swagger3.0文档

发表于   |   分类于   |  

最新公司新开了一个项目 惯例还是使用的 php laravel 框架 既然 Laravel5.5都发布那么久了 就来个试试吧
顺便把PHP也升级到了7.2 作死折腾出了好多幺蛾子了 以后再慢慢讲吧 因为是做微服务API使用的项目 (别问我为什么要用PHP来写 因为我只有PHP比较熟) 所以准备集成下 Swagger 文档 果不其然又出幺蛾子了 下面记录下

准备工作

Laravel 使用的 5.5 版本 新建个项目测试下吧

composer create-project --prefer-dist laravel/laravel test5 "5.5.*"

本次使用的是 darkaonline/l5-swagger 这个包 具体看这 https://github.com/DarkaOnLine/L5-Swagger

安装swagger

因为laravel是5.5的 为了对应使用下面的

composer require "darkaonline/l5-swagger:5.5.*"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 5 installs, 0 updates, 0 removals
  - Installing swagger-api/swagger-ui (v3.19.0): Downloading (100%)
  - Installing symfony/yaml (v4.1.4): Downloading (100%)
  - Installing doctrine/annotations (v1.6.0): Loading from cache
  - Installing zircote/swagger-php (3.0.0): Loading from cache
  - Installing darkaonline/l5-swagger (5.5.8.3): Downloading (100%)
Writing lock file
Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover
Discovered Package: darkaonline/l5-swagger
Discovered Package: fideloper/proxy
Discovered Package: laravel/tinker
Discovered Package: nesbot/carbon
Package manifest generated successfully.

等一会 看到最后的generated successfully 就表示安装成功了

生成配置文件

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

1
2
3
Copied File [/vendor/darkaonline/l5-swagger/config/l5-swagger.php] To [/config/l5-swagger.php]
Copied Directory [/vendor/darkaonline/l5-swagger/resources/views] To [/resources/views/vendor/l5-swagger]
Publishing complete.

然后你会看到在config文件夹下多了一个 l5-swagger.php 的配置文件 相关配置都在这里

然后编辑.env 文件 增加如下

1
2
3
4
# swagger配置
# 表示开启每次自动生成文档 和使用的swagger版本是3.0 
L5_SWAGGER_GENERATE_ALWAYS=true
SWAGGER_VERSION=3.0
这里有坑 文档版本3.0和2.0的不一样的书写格式 具体的如果使用2.0的话自己去研究吧 这里只讲3.0的文档生成

配置自动加载swagger服务

编辑 config/app.php 文件 找到 providers 数组 L5Swagger\L5SwaggerServiceProvider::class, 把这个加进去 后面都会自动加载该服务了

好了准备工作已经完成 下面开始生成API文档

生成Swagger文档

下面创建一个 TestController

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?php
namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
/**
 * @SWG\Swagger(
 *     @OA\Info(title="XX接口说明文档", version="0.1")
 * )
 */
class TestController extends Controller
{
    /**
     * @OA\Post(
     *     path="/show",
     *     tags={"XXAPI"},
     *     summary="获取时间接口",
     *     description="获取时间接口",
     *     operationId="TimeShow",
     *     deprecated=false,
     *     @OA\Parameter(
     *         name="access_token",
     *         in="query",
     *         description="用户授权",
     *         required=true,
     *         @OA\Schema(
     *             type="string"
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="操作成功返回"
     *     ),
     *     @OA\Response(
     *         response=400,
     *         description="发生错误"
     *     )
     * )
     */
    public function show()
    {
        echo date('Y-m-d H:i:s', time());
    }
}

注意：类上面的那个 oa/info 的东西项目中的类 只需要有一个这个声明就可以了 不需要每个类上面都写上这个

还需要写一个方法 配置上一段swagger的语法

然后执行 php artisan l5-swagger:generate 即可生成文档了

下面2个报错分别是我没有写 title 和 方法表述的时候报错

1
2
3
4
5
6
7
8
9
10
11
12
13
14
vagrant@homestead:~/code/test5$ php artisan l5-swagger:generate
Regenerating docs
In Logger.php line 39:
  Required @OA\Info() not found
vagrant@homestead:~/code/test5$ php artisan l5-swagger:generate
Regenerating docs
In Logger.php line 39:
  Required @OA\PathItem() not found

下面在补一个 get 请求的声明

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
26
27
28
29
30
31
/**
     * @OA\Get(
     *     path="/hello",
     *     tags={"XXAPI"},
     *     summary="说你好接口",
     *     description="说你好接口",
     *     operationId="SayHello",
     *     deprecated=false,
     *     @OA\Parameter(
     *         name="access_token",
     *         in="query",
     *         description="用户授权",
     *         required=true,
     *         @OA\Schema(
     *             type="string"
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="操作成功返回"
     *     ),
     *     @OA\Response(
     *         response=400,
     *         description="发生错误"
     *     )
     * )
     */
    public function hello()
    {
        echo "hello";
    }

在 config/l5-swagger.php 有配置访问文档的url 在其中的 route 数组下的 api 参数 你可以改成你喜欢的访问后缀 他默认是 api/documentation

下面我们访问 我们的项目 我的是 http://local.test5.show/api/documentation 每次他都会重新生成一份 api-docs.json 的文件 然后根据这个文件来生成我们看到的swagger文档 api-docs.json 在 storage/api-docs/api-docs.json 你可以根据配置文件自己更改位置等

最后看下最后效果

swagger

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