安裝swagger-php

zircote/swagger-php是swagger的php版,是一個擴展庫,我們需要安裝使用

composer require zircote/swagger-php

安裝Swagger ui

swagger-ui

下載后把dist目錄下的文件復(fù)制到項目public/doc目錄下, 這個目錄可以自定義, 通俗來講就是放到項目能訪問到的目錄下, 然后再將swagger-initializer.js文件里的url改成./openapi.json, 這里的openapi.json是生成文檔后的文件名,意思是訪問本地的openapi.json文件

window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "./openapi.json", //修改這里
        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
}

在項目根目錄創(chuàng)建文件 swagger.php

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

$gen = \OpenApi\Generator::class;

$openapi = $gen::scan([__DIR__.'/app/controller']);
//生成json, 可以用來對yapi的同步
file_put_contents(__DIR__.'/public/docs/openapi.json', $openapi->toJson());

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

header("Location: /public/doc/index.html");

./app/controller代表生成文檔時需要掃描的目錄, ./public/docs是生成文檔文件的位置(即生成openapi.json)

生成文檔執(zhí)行命令即可生成文檔

php swagger.php

我的建議是在nginx中配置swagger生成服務(wù)（swagger當(dāng)作入口文件），nginx配置如下：

server {
        listen        8788;
        server_name  localhost;
        root   "C:/phpstudy_pro/WWW/genesis/";
         location / {
            index swagger.php;

            if ( -f $request_filename) {
                break;
            }
            if ( !-e $request_filename) {
                rewrite ^(.*)$ /public/docs/openapi.json last;
                break;
            }

        }

        location ~ \.php(.*)$ {
            fastcgi_pass   127.0.0.1:9000;
            fastcgi_index  admin.php;
            fastcgi_split_path_info  ^((?U).+\.php)(/?.+)$;
            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
            fastcgi_param  PATH_INFO  $fastcgi_path_info;
            fastcgi_param  PATH_TRANSLATED  $document_root$fastcgi_path_info;
            include        fastcgi_params;
        }
}

在控制器中（app/controller）注釋如下：
/**

• @OA\Server(url="/report", description="這是下面所有Api前綴(使用json序列化傳輸，所有上報字段json后寫入messageData，再通過sjon傳到服務(wù)端)")
• @OA\Info(title="測試", version="0.1")
  */

class Report
{

   /**
 * @OA\Post(
 *     path="/add",
 *     summary="上報信息",
 *     description="上報信息接口",
 *     tags={"Report"},
 *     @OA\RequestBody(
 *         @OA\MediaType(
 *             mediaType="json",
 *             @OA\Schema(
 *                 @OA\Property(
 *                     property="device",
 *                     type="int",
 *                     description=" 0 未知 1 安卓  2 IOS ",
 *                 ),
 * 
 *                 messageData={"device": 1, "type": "startUp", "uuid": 12345678}
 *             )
 *         )
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="OK",
 *        @OA\MediaType(mediaType="json",
 *          @OA\Schema(
 *              @OA\Property(property="resultCode",type="string",description="返回code"),
 *              @OA\Property(property="resultInfo",type="string",description="返回錯誤信息"),
 *              @OA\Property(property="messageData",type="string",description="返回數(shù)據(jù)"),
 *             )
 *         )
 *     )
 * )
 */
    public function add(Request $request)
    {
    }

}