2023年PHP项目使用swaager生成api文档

现在网络上停留的一些教程都有点老了，要不是命令不对，要么是发现教程中需要修改的文件找不到，

我在这里整合一下当下PHP使用swaager生成api文档的方法。

1.安装Swagger-PHP

在项目根目录下执行命令安装Swagger-PHP

composer require zircote/swagger-php

执行完毕后检查下vendor文件下是否有zircote/swagger-php文件

2.安装swagger-ui

https://github.com/swagger-api/swagger-ui

将源码下载下来，然后将根目录下的dist文件复制到项目public下即可(若没public目录就复制到一个在浏览器中可以访问到的一个目录下即可)

在项目public目录下创建swagger-docs目录(保存生成的文档swagger.json)

3.编写接口文档

<?php

namespace app\controller;

use support\Request;

class IndexController
{

/**
 * @OA\Get(
 * path="/index",
 * @OA\Response(
 * response="200",
 * description="The data"
 * )
 * )
 */
 public function index(Request $request){
return json(["code"=>200,"message"=>"访问成功"]);
}

}

详细的编写方式请查看官网Home | Swagger-PHP (zircote.github.io)

4.生成接口文档

php vendor/zircote/swagger-php/bin/openapi vendor/zircote/swagger-php/Examples -o swagger-docs/swagger.json

• php：这是PHP解释器，用于执行后续的脚本。
• vendor/zircote/swagger-php/bin/openapi：这部分命令运行位于”vendor/zircote/swagger-php/bin”目录中的PHP脚本。脚本的名称是”openapi”，由Swagger-PHP库提供。
• vendor/zircote/swagger-php/Examples：这是包含定义API文档的源代码或注释的目录的路径。你应该将其替换为实际的PHP代码或注释的路径。
• -o swagger-docs/swagger.json：这部分指定了生成的OpenAPI文档的输出位置和格式。在这种情况下，生成的文档将保存为名为”swagger.json”的JSON文件，保存在”swagger-docs”目录中。您可以根据需要调整输出位置和格式。

以上命令注释为chatgpt生成，我这里在做一个通俗的解释

php为执行命令

vendor/zircote/swagger-php/bin/openapi为你插件的路径

vendor/zircote/swagger-php/Examples为生成接口文档时扫描的文件路径（一般就是你的控制器路径）

-o swagger-docs/swagger.json为生成的的文档保存的路径

如果按照我上面的配置那么这里的命令就是

php vendor/zircote/swagger-php/bin/openapi app/controller/ -o public/swagger-docs/swagger.json

这里控制器的路径可能需要修改一下，命令如果没有报错就会发现public/swagger-docs文件下已经有了swagger.json文件

5.最终配置以及访问swagger-ui页面

找到项目目录下public/doc/dist/swagger-initializer.js文件

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">

  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    url: "http://127.0.0.1:8787/swagger-docs/swagger.json",//修改这里，改成你项目运行时访问swagger.json的路径
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

  //</editor-fold>
};

最后在浏览器访问public/doc/dist/index.html文件，就能访问到swagger-ui页面

补充：如果一个项目需要生成多个文档

修改public/doc/dist/swagger-initializer.js文件

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">

  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    //url: "http://127.0.0.1:8787/swagger-docs/swagger.json",//修改这里，改成你项目运行时访问swagger.json的路径
    urls:[
      {url:"http://127.0.0.1:8787/swagger-docs/swagger1.json",name:"文档1"},
      {url:"http://127.0.0.1:8787/swagger-docs/swagger2.json",name:"文档2"}
    ], //开启Topbar插件支持多个文档
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

  //</editor-fold>
};