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 协议》,转载必须注明作者和本文链接
本帖由系统于 2年前 自动加精
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
讨论数量: 6

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

2年前 评论

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

2年前 评论
喝卵形 (楼主) 2年前
哪吒的狗腿子 2年前

挺好的, 学习了, :blush:

1年前 评论

问下大佬,resource里面有关联关系的resource嵌套,注释该怎么写?

1年前 评论

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