36°

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

  1. 下载swagger-ui下载
wget https://gitee.com/qzeroq/swagger-ui/repository/archive/v3.25.0?format=zip
  1. 下载swagger-php下载,改变版本要求php>=7.0
wget https://gitee.com/qzeroq/swagger-php/repository/archive/3.0.1?format=zip
  1. 安装依赖
[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 } ]

  1. 创建软连接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/下执行

  1. 创建nginx虚拟站点
[root@localhost ~]# cd /etc/nginx/conf.d/
[root@localhost conf.d]# pwd
/etc/nginx/conf.d
[root@localhost conf.d]# vim swagger.cuobian.com.conf
server {
        listen       80;
        server_name  swagger.cuobian.com;
        charset utf-8;
    root /www/api/api-www/dist;
    index index.html;
    location / {
        try_files $uri $uri/ /index.html;
    }

}

  1. 创建文件夹/www/api/api-www/dist
[root@localhost ~]# mkdir /www/api/api-www/dist
  1. 拷贝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]#
  1. 生成测试的文档
#这个是生成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
  1. 重启nginx
[root@localhost dist]# service nginx reload
  1. 浏览器访问
  2. 示例
  • 文件结构
.
├── 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

本文由【请叫我足下】发布于开源中国,原文链接:https://my.oschina.net/php7/blog/3160185

全部评论: 0

    我有话说: