本文小编为大家详细介绍“PHP如何使用Swagger生成好看的API文档”，内容详细，步骤清晰，细节处理妥当，希望这篇“PHP如何使用Swagger生成好看的API文档”文章能帮助大家解决疑惑，下面跟着小编的思路慢慢深入，一起来学习新知识吧。
一、安装swagger-php
composer require zircote/swagger-phpswagger-php提供了命令行工具，所以可以全局安装，然后把工具的路径加到PATH里去。
composer global require zircote/swagger-php然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到，就不研究了。
二、设置一个输出api文档数据的接口
a）、生成一个控制器： SwaggerController
b）、添加一个方法： getJSON()
public function getJSON()
{
$swagger = OpenApiGenerator::scan([app_path('Http/Controllers/')]);
return response()->json($swagger, 200);
}有的文章里写 Swaggerscan()，但我这里报错，说找不到这个类。查了官方文档，要用 OpenApiGenerator::scan()。有可能是新版本做了修改。
c）、设置路由
api.php 或者 web.php都行，路径不同而已。本人选择api.php。所以访问路径要加个前缀：/api。
Route::group(['prefix' => 'swagger'], function () {
Route::get('json', [AppHttpControllersSwaggerController::class, 'getJSON']);
});d）、测试访问
访问 http://localhost:8000/api/swagger/json 如果看到页面正常输出json，说明配置成功了。不然就按错误提示一项项去修改吧。
三、使用
GET方法
/**
* @OAGet(
* tags={"数据管理"},
* summary="数据查询",
* path="/api/data/search",
* @OAResponse(response="200", description="Display a listing of projects."),
* @OAParameter(
* description="数据名称",
* in="query",
* name="name",
* required=false,
* @OASchema(type="string"),
* ),
* @OAParameter(
* description="状态",
* in="query",
* name="status",
* required=false,
* @OASchema(type="integer"),
* ),
* @OAParameter(
* description="每页记录数",
* in="query",
* name="page-size",
* required=false,
* @OASchema(type="integer"),
* ),
* @OAParameter(
* description="当前页码",
* in="query",
* name="current-page",
* required=false,
* @OASchema(type="integer"),
* ),
* )
*/这里面:
in 表示该参数出现在哪里。 query的话就是用&拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里；cookie 自然是放在cookie里。
这个版本里formData, body这些都没有了。
required 看名字就知道 true是必填项，false是选填项。
POST方法
/**
* @OAPost(
* tags={"数据管理"},
* summary="添加数据",
* path="/api/data",
* @OAResponse(response="200", description="Display a listing of projects."),
* @OARequestBody(
* @OAMediaType(
* mediaType="x-www-form-urlencoded",
* @OASchema(
* ref="#/components/schemas/DataModel",
* ),
* ),
* ),
* )
*/因为本人的前端代码post都是表单提交，所以这里的post方法要用@OARequestBody。
@OAParameter是参数，是可以放到url上，但是post的表单提交，数据是不出现在url上的。
@OAMediaType 这个: x-www-form-urlencoded 表单提交；application/json 提交json格式的数据；multipart/form-data 文件上传；
* @OASchema(
* ref="#/components/schemas/DataModel",
* ),这个是关联到一个已经定义好的schema上，省得使用相同数据的每个接口注释里都写一遍。
这里也可以单独写：
* @OASchema(
* required={"name", "code"},
* @OAProperty(property="name", type="string", title="姓名", description="这是姓名"),
* @OAProperty(property="code", type="string", title="代码", description="这是代码"),
* @OAProperty(property="phone", type="string", title="电话", description="这是电话"),
* ),上面这样，有多少个参数就写多少个@OAProperty。这里的required是个数组，写在里面的都是必填项。
四、显示swagger ui
解压后，把目录里的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文档了。