前言

在团队合作开发时, 特别是在前后端分离的项目中,后端编写接口后,需要和前端对接有哪些接口, 此时,接口文档就显得很重要了, 之前我用的 mpociot/laravel-apidoc-generator, 但是局限于laravel框架中,团队中其他成员有使用thinkphp的,所以一个通用的接口文档工具就显得如此重要

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。


总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

Swagger并不是简单的文档工具, 很强大, 这里我们使用的是它的接口文档功能

在PHP项目中使用

前提

需要Linux, PHP, Laravel(这里举例是用的laravel, 理论所有php框架都通用)

安装swagger-php

zircote/swagger-php是swagger的php版,是一个扩展库,我们需要安装使用

1

composer require zircote/swagger-php

安装Swagger ui

swagger-ui

下载后把dist目录下的文件复制到项目public/docs目录下, 这个目录可以自定义, 通俗来讲就是放到项目能访问到的目录下, 然后再将index.html文件里的url改成./openapi.yaml, 这里的openapi.yaml是生成文档后的文件名,意思是访问本地的openapi.yaml文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "./openapi.yaml", //修改这里
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
}

生成

在项目根目录创建文件 swagger.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?php
require("vendor/autoload.php");

$openapi = OpenApi\scan([__DIR__.'/app']);

//生成json, 可以用来对yapi的同步
file_put_contents(__DIR__.'/public/docs/openapi.json', $openapi->toJson());

//生成yaml
shell_exec("./vendor/bin/openapi ./app -o ./public/docs");

注意: 这里需要Linux环境, ./app代表生成文档时需要扫描的目录, ./public/docs是生成文档文件的位置

生成文档执行命令即可生成文档

1

php swagger.php

使用

BaseController.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<?php

namespace App\Http\Controllers\Home;

use OpenApi\Annotations as OA;

/**
 * @OA\Server(url="/api/home", description="这是下面所有Api前缀")
 *  @OA\Info(title="Api文档", version="1.0.0")
 */
class BaseController
{

}

CurdController.php

 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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

<?php

namespace App\Http\Controllers\Home;

use OpenApi\Annotations as OA;

class CurdController extends BaseController
{
    /**
     * @OA\Get(summary="get",path="/get/{id}",tags={"curd"},description="简介",
     *     @OA\Parameter(name="Authorization",in="header",required=true,description="Bearer"),
     *     @OA\Parameter(name="id",in="path",required=true,description="id"),
     *     @OA\Response(response="200", description="获取成功",
     *      @OA\MediaType(
     *          mediaType="application/json",
     *          @OA\Schema(ref="#/components/schemas/Info"),
     *      )
     *     )
     * )
     */
    public function get()
    {

    }

    /**
     * @OA\Post(summary="post",path="/post",tags={"curd"},description="简介"
     *     @OA\Parameter(name="Authorization",in="header",required=true,description="Bearer"),
     *     @OA\RequestBody(
     *         @OA\MediaType(mediaType="application/json",
     *             @OA\Schema(
     *                 @OA\Property(property="integer",type="integer",description="简介"),
     *                 @OA\Property(property="string",type="string",description="简介"),
     *                 @OA\Property(property="number",type="number",description="简介"),
     *             )
     *         )
     *     ),
     *     @OA\Response(response="200", description="下单成功")
     * )
     */
    public function post()
    {

    }
    /**
     * @OA\Post(summary="上传文件",path="/upload/file/{type}",tags={"Auth"},description="上传文件",
     *     @OA\Parameter(name="Authorization",in="header",required=true,description="Bearer"),
     *     @OA\Parameter(name="type",in="path",required=true,description="类型"),
     *     @OA\RequestBody(
     *         @OA\MediaType(mediaType="multipart/form-data",
     *             @OA\Schema(
     *                 @OA\Property(property="file",type="file",description="文件")
     *             )
     *         )
     *     ),
     *     @OA\Response(response="200",description="获取成功",
     *     @OA\MediaType(mediaType="application/json",
     *             @OA\Schema(
     *                 @OA\Property(property="url",type="string",description="路径"),
     *                 @OA\Property(property="originalName",type="string",description="原始名称"),
     *                 @OA\Property(property="dirName",type="string",description="文件名称"),
     *                 @OA\Property(property="extension",type="string",description="文件类型"),
     *                 @OA\Property(property="host",type="string",description="当前域名"),
     *             )
     *         )
     *      )
     * )
     */
    public function uploadFile()
    {

    }
}

Info.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

<?php

namespace App\Models;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema()
 */
class Info
{

    /**
     * @OA\Property(property="name", type="string", description="名称")
     */

    /**
     * @OA\Property(property="number", type="integer", description="数量")
     */
}

这里给的是简单的使用, 包含接口前缀, 文档说明, GET POST的写法, 关联Model字段显示的写法,数据类型为json, 更多操作请看文档