太谷网站建设,广州东站建站时间,网站开发专业分析,住房与城乡建设部网站职责PHP使用Swagger生成好看的API文档不是不可能#xff0c;而是非常简单。首先本人使用Laravel框架#xff0c;所以在Laravel上安装swagger-php。一、安装swagger - phpcomposer require zircote/swagger-phpswagger-php提供了命令行工具#xff0c;所以可以全局安装#xff0…PHP使用Swagger生成好看的API文档不是不可能而是非常简单。首先本人使用Laravel框架所以在Laravel上安装swagger-php。一、安装swagger - phpcomposer require zircote/swagger-phpswagger-php提供了命令行工具所以可以全局安装然后把工具的路径加到PATH里去。composer global require zircote/swagger-php然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到就不研究了。二、设置一个输出api文档数据的接口a、生成一个控制器 SwaggerControllerb、添加一个方法 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方法 /** * OA\Get(* tags{数据管理},* summary数据查询,* path/api/data/search,* OA\Response(response200, descriptionDisplay a listing of projects.),* OA\Parameter(* description数据名称,* inquery,* namename,* requiredfalse,* OA\Schema(typestring),* ),* OA\Parameter(* description状态,* inquery,* namestatus,* requiredfalse,* OA\Schema(typeinteger),* ),* OA\Parameter(* description每页记录数,* inquery,* namepage-size,* requiredfalse,* OA\Schema(typeinteger),* ),* OA\Parameter(* description当前页码,* inquery,* namecurrent-page,* requiredfalse,* OA\Schema(typeinteger),* ),* )*/这里面:in 表示该参数出现在哪里。 query的话就是用拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里cookie 自然是放在cookie里。这个版本里formData, body这些都没有了。required 看名字就知道 true是必填项false是选填项。POST方法 /** * OA\Post(* tags{数据管理},* summary添加数据,* path/api/data,* OA\Response(response200, descriptionDisplay a listing of projects.),* OA\RequestBody(* OA\MediaType(* mediaTypex-www-form-urlencoded,* OA\Schema(* ref#/components/schemas/DataModel,* ),* ),* ),* )*/因为本人的前端代码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{name, code},* OA\Property(propertyname, typestring, title姓名, description这是姓名),* OA\Property(propertycode, typestring, title代码, description这是代码),* OA\Property(propertyphone, typestring, title电话, description这是电话),* ),上面这样有多少个参数就写多少个OA\Property。这里的required是个数组写在里面的都是必填项。其它方法都差不多以后有用到了再记录。四、显示swagger ui下载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 descChangeable Configuration Block// the following lines will be replaced by docker/configurator, when it runs in a docker-containerwindow.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文档了。-完-
