基于swagger-php、swagger-ui构建自动化API文档

下载swagger-ui下载

wget https://gitee.com/qzeroq/swagger-ui/repository/archive/v3.25.0?format=zip

下载swagger-php下载,改变版本要求php>=7.0

wget https://gitee.com/qzeroq/swagger-php/repository/archive/3.0.1?format=zip

安装依赖

[root@localhost local]# cd src/
[root@localhost src]# cd swagger-php
[root@localhost swagger-php]# pwd
/usr/local/src/swagger-php
[root@localhost swagger-php]# ll
total 136
drwxr-xr-x  2 root root   131 Jan 19 10:12 bin
-rw-r--r--  1 root root   108 Nov 16  2018 Changelog.md
-rw-r--r--  1 root root  1450 Jan 19 10:07 composer.json
-rw-r--r--  1 root root 94619 Jan 19 10:12 composer.lock
drwxr-xr-x  4 root root   154 Nov 16  2018 docs
drwxr-xr-x  9 root root   156 Nov 16  2018 Examples
-rw-r--r--  1 root root 11358 Nov 16  2018 LICENSE-2.0.txt
-rw-r--r--  1 root root   336 Nov 16  2018 phpunit.xml.dist
-rw-r--r--  1 root root  3480 Nov 16  2018 README.md
drwxr-xr-x  4 root root  4096 Nov 16  2018 src
drwxr-xr-x  4 root root  4096 Nov 16  2018 tests
drwxr-xr-x 17 root root  4096 Jan 19 10:12 vendor
[root@localhost swagger-php]# composer install

注意：执行composer install 之前一定要先vim composer.json将源切换成阿里的composer源，提升安装速度 "repositories": [ { "type": "composer", "url": "https://mirrors.aliyun.com/composer/" }, { "packagist": false } ]

创建软连接swagger-php

[root@localhost swagger-php]# ln -s /usr/local/src/swagger-php/bin/openapi /usr/sbin/swagger-php

注意：这个必须写成php7.1 /usr/sbin/swagger-php不能写成php7.1 swagger-php，否则会报错Could not open input file: swagger-php，除非这个命令是在目录/usr/sbin/下执行

创建nginx虚拟站点

[root@localhost ~]# cd /etc/nginx/conf.d/
[root@localhost conf.d]# pwd
/etc/nginx/conf.d
[root@localhost conf.d]# vim swagger.domian.com.conf
server {
        listen       80;
        server_name  swagger.domian.com;
        charset utf-8;

        root /www/api/api-www/dist;
        index index.html;
        location / {
            try_files $uri $uri/ /index.html;
        }

}

创建文件夹/www/api/api-www/dist

[root@localhost ~]# mkdir /www/api/api-www/dist

拷贝swagger-ui的dist文件到/www/api/api-www/dist，并创建/www/api/api-www/dist/api文件夹用来存放接口文件

[root@localhost ~]# cd  /www/api/api-www/dist
[root@localhost dist]# pwd
/www/api/api-www/dist
[root@localhost dist]# cp /www/api/swagger-ui/dist/ ./ -a
[root@localhost dist]# mkdir api
[root@localhost dist]# ll
total 8848
drwxr-xr-x 2 root root      60 Jan 19 11:33 api
-rw-r--r-- 1 root root     445 Sep  8  2018 favicon-16x16.png
-rw-r--r-- 1 root root    1141 Sep  8  2018 favicon-32x32.png
-rw-r--r-- 1 root root    1375 Jan 19 11:32 index.html
-rw-r--r-- 1 root root    2388 Sep  8  2018 oauth2-redirect.html
-rw-r--r-- 1 root root  938270 Sep  8  2018 swagger-ui-bundle.js
-rw-r--r-- 1 root root 3966469 Sep  8  2018 swagger-ui-bundle.js.map
-rw-r--r-- 1 root root  153754 Sep  8  2018 swagger-ui.css
-rw-r--r-- 1 root root      91 Sep  8  2018 swagger-ui.css.map
-rw-r--r-- 1 root root  753316 Sep  8  2018 swagger-ui.js
-rw-r--r-- 1 root root 1477662 Sep  8  2018 swagger-ui.js.map
-rw-r--r-- 1 root root  305717 Sep  8  2018 swagger-ui-standalone-preset.js
-rw-r--r-- 1 root root 1432074 Sep  8  2018 swagger-ui-standalone-preset.js.map
[root@localhost dist]#

生成测试的文档

#这个是生成yaml格式的文档
[root@localhost ~]# php7.1 /usr/sbin/swagger-php /usr/local/src/swagger-php/Examples/example-object/ -o /www/api/api-www/dist/api/test.yaml
#这个是生成json格式的文档
[root@localhost ~]# php7.1 /usr/sbin/swagger-php /usr/local/src/swagger-php/Examples/example-object/ -o /www/api/api-www/dist/api/test.json

9.修改文件/www/api/api-www/dist/index.html

[root@localhost dist]# vim /www/api/api-www/dist/index.html

 // Build a system
      const ui = SwaggerUIBundle({
      //修改这里url指向生成的接口文件位置（注意跨域问题，这里不存在，因为在同一个域名下）
      //原始链接：url: "https://petstore.swagger.io/v2/swagger.json",
        url: "http://swagger.domain.com/api/test.yaml",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      window.ui = ui

重启nginx

[root@localhost dist]# service nginx reload

浏览器访问
示例

文件结构

.
├── app
│   ├── Http
│   │   ├── Controllers
│   │   │   ├── Admin
│   │   │   │   ├── TestController.php
│   │   │   └── swagger-v3.php

TestController.php文件内容

<?php

class TestController extends Controller
{
    /**
     * @OA\Get(
     *     path="/test/findByNames",
     *     summary="通过标签查找",
     *     tags={"示例"},
     *     description="这是个接口示例",
     *     operationId="findPetsByTags",
     *     @OA\Parameter(
     *         name="names",
     *         in="query",
     *         description="标签名",
     *         required=true,
     *         @OA\Schema(
     *           type="array",
     *           @OA\Items(type="string"),
     *         ),
     *         style="form"
     *     ),
     *   @OA\Response(
     *     response=200,
     *     description="返回码",
     *     @OA\JsonContent( type="json", example=
     *     {
     *       "code": 0,
     *       "msg": "获取列表信息成功",
     *       "data": {
     *            "list": {
     *                 {
     *                     "id": 8,
     *                     "img_url": "http:/2725/e418c0e883.jpg",
     *                     "name": "首页banner",
     *                     "plat": "业端",
     *                     "banner": "首页",
     *                     "jump": "无链接",
     *                     "jump_url": "",
     *                     "sort": 1,
     *                     "status": 2,
     *                     "start_time": "2020-01-01 00:00:00",
     *                     "end_time": "2020-10-31 23:59:59",
     *                     "is_all_open": 1,
     *                     "status_name": "投放中",
     *                     "time": "2020-01-01 00:00:00"
     *                }
     *            },
     *            "count": 2
     *       }
     *     }
     *     )
     *   ),
     * )
     */
    public function findByNames()
    {
        return "openApi3.0";
    }
}

swagger-v3.php文件内容

<?php

/**
 * @OA\OpenApi(
 *     @OA\Info(
 *         version="1.0.0",
 *         title="API",
 *         description="文档",
 *     ),
 *     @OA\Server(
 *         description="测试环境地址",
 *         url="http://test.domain.com/"
 *     ),
 *     @OA\Server(
 *         description="本地开发环境",
 *         url="http://dev.domain.com/"
 *     ),
 * )
 */

生成接口文档

php7.1 /usr/sbin/swagger-php /app/Http/Controllers/ -o /www/api/api-www/dist/api/test.json

浏览器查看

番外知识点

坑1. @OA\Get方法必须写在一个类文件中，否则会报如下错误:

Required @OA\PathItem() not found

来源：oschina

链接：https://my.oschina.net/php7/blog/3160185

标签

php

swagger

Swagger UI