基于swaggerphp、swaggerui构建自动化API文档

Z时代
2024-01-10
分类：综合

创建软连接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
{
    /**
     * @OAGet(
     *     path="/test/findByNames",
     *     summary="通过标签查找",
     *     tags={"示例"},
     *     description="这是个接口示例",
     *     operationId="findPetsByTags",
     *     @OAParameter(
     *         name="names",
     *         in="query",
     *         description="标签名",
     *         required=true,
     *         @OASchema(
     *           type="array",
     *           @OAItems(type="string"),
     *         ),
     *         style="form"
     *     ),
     *   @OAResponse(
     *     response=200,
     *     description="返回码",
     *     @OAJsonContent( 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
/**
 * @OAOpenApi(
 *     @OAInfo(
 *         version="1.0.0",
 *         title="API",
 *         description="文档",
 *     ),
 *     @OAServer(
 *         description="测试环境地址",
 *         url="http://test.domain.com/"
 *     ),
 *     @OAServer(
 *         description="本地开发环境",
 *         url="http://dev.domain.com/"
 *     ),
 * )
 */