现在网络上停留的一些教程都有点老了,要不是命令不对,要么是发现教程中需要修改的文件找不到,
我在这里整合一下当下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页面
![2023年PHP项目使用swaager生成api文档 https://cdn.dykyzdh.cn/wp-content/uploads/2023/10/swagger-1024x411.png](https://cdn.dykyzdh.cn/wp-content/uploads/2023/10/swagger-1024x411.png)
补充:如果一个项目需要生成多个文档
修改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>
};