Laravel 8 开发中使用 swagger-php 3 生成文档

最近在新项目开发的过程中我发现 swagger-php 升级了版本,而且和以前的文档注释写法有了蛮多的差别。官方文档也写的不是很详细,在这里我将结合自己封装的案例将 Swagger-PHP v3.x 的一些用法分享给大家。

介绍

Laravel 8 开发中使用 swagger-php 3 生成文档

  • 文档生成后效果

Laravel 8 开发中使用 swagger-php 3 生成文档

安装

  • composer require darkaonline/l5-swagger
  • php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
  • composer require laravel/sanctum

Swagger 可复用的公用参数

  • 我会把文档的一些公共参数( 如 @OA\OpenApi , @OA\OpenApi, @OA\SecurityScheme)写到 ApiController 里面。代码如下

Laravel 8 开发中使用 swagger-php 3 生成文档

  • 图片对应

Laravel 8 开发中使用 swagger-php 3 生成文档

Swagger 请求参数

POST 请求

swagger-php 3.* 以前我们如果 Post 请求参数很多,那么在控制器我们可能写很多的注释。导致代码特别冗余。 swagger-php 3.* 我是通过 表单验证 来解决这个问题的。同时代码也更清晰规范。

Laravel 8 开发中使用 swagger-php 3 生成文档

在上面代码中,我们看不到任何需要请求的参数,@OA\RequestBody 通过 ref 关联到 #/components/schemas/RegisterRequest,而我们刚好有个表单请求类 RegisterRequest。在 swagger-php 3.* 我们可以把文档 post 参数的注释放到表单请求类 RegisterRequestRegisterRequest 代码如下:

Laravel 8 开发中使用 swagger-php 3 生成文档

  • 生成文档效果

Laravel 8 开发中使用 swagger-php 3 生成文档

GET 请求

我们以获取用户列表和获取用户详情,分别演示路由参数和请求参数注释如何编写。

Laravel 8 开发中使用 swagger-php 3 生成文档

Laravel 8 开发中使用 swagger-php 3 生成文档

Laravel 8 开发中使用 swagger-php 3 生成文档

Laravel 8 开发中使用 swagger-php 3 生成文档

Swagger 返回参数

在 Api 返回的时候,有可能是列表,有可能是对象。如果对象参数特别多,按以前我们可能在控制器写很多注释文档,导致代码很难看,我在项目开发中是将返回的注释写到 API 资源 来解决这个问题。

返回数组列表

Laravel 8 开发中使用 swagger-php 3 生成文档

UserResource 代码

Laravel 8 开发中使用 swagger-php 3 生成文档

效果

Laravel 8 开发中使用 swagger-php 3 生成文档

返回对象

Laravel 8 开发中使用 swagger-php 3 生成文档

Laravel 8 开发中使用 swagger-php 3 生成文档

从上面我们可以发现 UserResource 是可以复用的,当 @OA\JsonContent(ref="#/components/schemas/UserResource") 里面有 type = array 返回的就是列表,不然就是对象。

异常返回

Laravel 8 开发中使用 swagger-php 3 生成文档

Laravel 8 开发中使用 swagger-php 3 生成文档

  • ApiNotFoundException 代码

Laravel 8 开发中使用 swagger-php 3 生成文档

总结

我是通过 API 资源表单验证 去拆解注释,同时达到 API 开发目录的规范。在我项目实际开发中,自己也基于这套规范收益良多。

本作品采用《CC 协议》,转载必须注明作者和本文链接
本帖由系统于 4周前 自动加精
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
讨论数量: 2

每个方法都要写这么一长串吗

4个月前 评论

注释写太多太复杂繁琐了
可以试试这个, 自动扫描控制器 自动生成接口文档
www.laraveladmin.cn
https://demo.laraveladmin.cn/api-doc/

4个月前 评论
喝卵形 (楼主) 4个月前
哪吒的狗腿子 4个月前

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!