PHP使用Swagger生成好看的API文档（php如何使用for循环写九九乘法表）速看

🌐 经济型：买域名、轻量云服务器、用途：游戏网站等《腾讯云》特点：特价机便宜适合初学者用点我优惠购买

🚀 拓展型：买域名、轻量云服务器、用途：游戏网站等《阿里云》特点：中档服务器便宜域名备案事多点我优惠购买

🛡️ 稳定型：买域名、轻量云服务器、用途：游戏网站等《西部数码》特点：比上两家略贵但是稳定性超好事也少点我优惠购买

文章摘要

这篇文章介绍了如何使用PHP的SWAGGER-PHP工具在Laravel框架中生成美观的API文档。文章分为以下步骤： 1. **安装SWAGGER-PHP**： - 使用composer命令安装：`composer require zircote/swagger-php` 和 `composer global require zircote/swagger-php`。 - 设置环境变量将工具路径添加到PATH中。 2. **生成API文档**： - 创建一个自定义Controller（如SwaggerController）。 - 在Controller中添加`getJSON()`方法，使用SWAGGER-PHP的`OpenApiGenerator::scan()`生成API文档。 - 配置路由（如`/api`），将`getJSON()`方法绑定到该路由。 3. **测试API文档**： - 访问`http://localhost:8000/api/swagger/json`，检查返回的JSON和网页界面。 4. **下载Swagger UI**： - 下载GitHub仓库中的Swagger UI代码。 - 解压后，将`dist`目录复制到Laravel的`public`目录下，并重命名为`swagger-ui`。 - 修改配置文件中的URL，自定义Swagger UI的启动地址。通过以上步骤，可以在Laravel应用中轻松生成和展示美观的API文档。文章还提供了详细的代码示例和配置说明，帮助开发者快速上手。

目录一、安装swagger-php二、设置一个输出api文档数据的接口三、使用四、显示swagger ui

PHP使用Swagger生成好看的API文档不是不可能，而是非常简单。

首先本人使用Laravel框架，所以在Laravel上安装swagger-php。

composer require zircote/swagger-php

swagger-php提供了命令行工具，所以可以全局安装，然后把工具的路径加到PATH里去。

composer global require zircote/swagger-php

然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到，就不研究了。

a）、生成一个控制器： SwaggerController

b）、添加一个方法： getJSON()

public function getJSON()
{
$swagger=\OpenApi\Generator::scan([app_path(‘Http/Controllers/’)]);
return response()->json($swagger, 200);
}

有的文章里写 \Swagger\scan()，但我这里报错，说找不到这个类。查了官方文档，要用 \OpenApi\Generator::scan()。有可能是新版本做了修改。

c）、设置路由

api.php 或者 web.php都行，路径不同而已。本人选择api.php。所以访问路径要加个前缀：/api。

Route::group([‘prefix’=> ‘swagger’], function () {
Route::get(‘json’, [\App\Http\Controllers\SwaggerController::class, ‘getJSON’]);
});

d）、测试访问

访问 http://localhost:8000/api/swagger/json 如果看到页面正常输出json，说明配置成功了。不然就按错误提示一项项去修改吧。

GET方法

这里面:

in 表示该参数出现在哪里。 query的话就是用&拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里；cookie 自然是放在cookie里。

这个版本里formData, body这些都没有了。

required 看名字就知道 true是必填项，false是选填项。

POST方法

因为本人的前端代码post都是表单提交，所以这里的post方法要用@OA\RequestBody。

@OA\Parameter是参数，是可以放到url上，但是post的表单提交，数据是不出现在url上的。

@OA\MediaType 这个: x-www-form-urlencoded 表单提交；application/json 提交json格式的数据；multipart/form-data 文件上传；

* @OA\Schema(
* ref=”#/components/schemas/DataModel”,
* ),

这个是关联到一个已经定义好的schema上，省得使用相同数据的每个接口注释里都写一遍。

这里也可以单独写：

* @OA\Schema(
* required=,
* @OA\Property(property=”name”, type=”string”, title=”姓名”, description=”这是姓名”),
* @OA\Property(property=”code”, type=”string”, title=”代码”, description=”这是代码”),
* @OA\Property(property=”phone”, type=”string”, title=”电话”, description=”这是电话”),
* ),

上面这样，有多少个参数就写多少个@OA\Property。

这里的required是个数组，写在里面的都是必填项。

其它方法都差不多，以后有用到了再记录。

下载swagger ui的代码： https://github.com/swagger-api/swagger-ui/releases

解压后，把目录里的dist目录，复制到laravel的public目录下面，改名为swagger-ui。文件名随便取，不冲突就行。

找开这个swagger-ui目录下的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: “/api/swagger/json”,
dom_id: ‘#swagger-ui’,
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: “StandaloneLayout”
});
//</editor-fold>
};

主要是改 url这项。改成前面设的路由地址。这里是 “/api/swagger/json”。

完成后访问 http://localhost:8000/swagger-ui/ 就能看到swagger形成的api文档了。

到此这篇关于PHP使用Swagger生成好看的API文档的文章就介绍到这了,更多相关PHP Swagger内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:Python实现处理apiDoc转swagger的方法详解