swagger太辣鸡了？
本教程是基于Laravel 生成swagger 为例子，其实这个东西和语言或者和框架基本没啥区别，因为都是用的公用的json ，通过程序扫描swagger预先规定的“语言”，生成结构存入json中，通过 swagger ui 展现出来（或者自己开发）。
对于php开发人员来说，有大部分同学很不喜欢swagger。 因为这个看上去写起来好麻烦啊，一想到分分钟用php写完的代码，写swagger要写10分钟，心里就抵触这个东西。
身边有Java开发的同学就知道他们很大一部分都用swagger，因为java要维护数据结构，而且swagger在java整合得更灵活。
这个时候java如果看到有php 说swagger反人类的东西，太麻烦了，上古时代的产物。那身边的java朋友会心里窃喜，这么好用的东西都不用，还说php是世界上最好的语言。
好了，上面只是本人的一些杂谈，主要是吸引一下各位（还没用过swagger的同学，可以了解一下哦）
我为啥用swagger
最近在写自动生成代码，其实现在Laravel 很多自动生成CURD的。比如像laravel-admin ，一条命令生成CURD，但是生成之后，数据看上去很冷。 比如有一些字段不需要显示，有一些是要select关联枚举的，有一些是 hasMany的，还有 overtrue（正超）的api脚手架也挺好的
那要你说 laravel-admin等类似的自动生成框架垃圾吗？ 那我都要替song哥打人了
框架已经做得很好了，但是要结合具体的业务，不同的行业，不同的程序员，不同的场景，一套代码怎么可能满足所有人。
因为我经常写一些小项目，和接一些项目，所以我就开始写适用于个人，或者公司的代码生成，模型和控制器生成不用说了，各位肯定也是自动化生成的，并生成注释。
但是模型关系，和枚举还是要写的，所以就想了想办法，统一做一个配置像这样子：
/**
* table relations
*/
'relations' => [
'users' => [
[
'relation' => "hasMany",
'table' => [
[
'table_name' => 'posts',
'target' => 'user_id', //目标表中的字段
'origin' => 'id',//本表的字段
'limit' => 5,//查询为10条
'list_show' => true,
'list_exist' => false,
'one_show' => false,
'create_relation' => false,//创建时，是否可以关联添加
],
],
],
]
先运行起来了，效果还行，分分钟生成代码，并有了关联关系的api接口。当然还可以加很多很多自定义的参数。
我这样生成了代码之后，我还要写文档给前端。于是有以下几个想法：
- 写成markdown的形式，再给前端
- 写成postman 的Json格式，再导入进去，方便自己调试接口，也可以给前端调试
- 对比了好几个api生成文档之后用swagger（当然，咱showdoc也不错哈）
完蛋，拍大腿，我用了swagger之后，为啥不早点用这个工具呢，这正是我所需要的东西，刚才我说了我写的自动化 有关联关系，和枚举自动识别并创建（这方面以后再分享）
- swagger生成的json又可以导入postman
- 又可以生成数据字典
- 请求的时候又可以前端选择枚举 ，绝了
但是swagger手写的话确实有点累，自动生成的，一点也不累，哈哈哈哈
看社区里有朋友写详细的Swagger ，但好像是v2版本的，所以还是写一篇博文分享给同仁们，结合官方的例子，把我需要的都整明白了。
下班了下班了，叨了这么多，这么迟回去又要被挨骂了。
L5-Swagger
https://github.com/DarkaOnLine/L5-Swagger
安装：
composer require "darkaonline/l5-swagger"
使用：
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
php artisan l5-swagger:generate
@OA\Info 为必须
🌰例子
/**
* @OA\Info(
* version="1.0.0",
* title="L5 OpenApi",
* description="L5 Swagger OpenApi description",
* @OA\Contact(
* email="darius@matulionis.lt"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
*/
get 请求
如果要匹配path中的数值则 in path 查询 in query
/**
* @OA\Get(
* path="/projects/{id}",
* operationId="getProjectById",
* tags={"Projects"},
* summary="Get project information",
* description="Returns project data",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation"
* ),
* @OA\Response(response=400, description="Bad request"),
* @OA\Response(response=404, description="Resource Not Found"),
* security={
* {
* "oauth2_security_example": {"write:projects", "read:projects"}
* }
* },
* )
*/
传入为枚举
* @OA\Parameter(
* name="status",
* in="query",
* description="状态",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* default="available",
* @OA\Items(
* type="string",
* enum = {"available", "pending", "sold"},
* )
* )
* ),
Body 为Json 方式提交
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="id",
* type="string"
* ),
* @OA\Property(
* property="name",
* type="string"
* ),
* example={"id": 10, "name": "Jessica Smith"}
* )
* )
* ),
使用结构Schema作为请求参数
* @OA\RequestBody(
* description="order placed for purchasing th pet",
* required=true,
* @OA\JsonContent(ref="#/components/schemas/UserModel")
* ),
Schema的使用
/**
* @OA\Schema(
* schema="UserModel",
* required={"username", "age"},
* @OA\Property(
* property="username",
* format="string",
* description="用户名称",
* example="小廖",
* ),
* @OA\Property(
* property="age",
* format="int",
* description="年龄",
* example=1,
* nullable=true,
* )
* )
*/
枚举
一个枚举单独创建一个Schema
/**
* @OA\Schema(
* schema="product_status",
* type="string",
* description="The status of a product",
* enum={"available", "discontinued"},
* default="available"
* )
*/
映射到模型中的具体字段
* @OA\Property(
* property="status",
* ref="#/components/schemas/product_status"
* ),
这样前端开发者就可以
关联模型
和枚举差不多，通过一个Property关联模型
* @OA\Property(
* property="user_detail",
* ref="#/components/schemas/UserModel2"
* ),
关联模型和枚举，可以自动生成请求的参数和，返回的结构
返回为模型结构
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/UserModel"),
* @OA\Items(ref="#/components/schemas/UserModel2")
* )
* ),
就比如那天前端小妹跟你说，哥哥，支付状态3代表什么，可能你很快的说出了是某某状态，但是问你11是啥状态，人都要沙雕了。
通过swagger 的Schema 能让前端人员摸清后端的结构信息，比如：
各位，这些都可以自动化编程，自动生成的，工作效率不要太爽
多个合并Schema
/**
* @OA\Schema(
* schema="UserModel",
* allOf={
* @OA\Schema(ref="#/components/schemas/UserModel2"),
* @OA\Schema(
* type="object",
* description="Represents an authenticated user",
* required={
* "email",
* "role",
* },
* additionalProperties=false,
* @OA\Property(
* property="email",
* type="string",
* example="user@example.com",
* nullable=true,
* ),
* )
* }
* )
*/
验证提供outh2 和apikey 两种方式，在存放全局配置中写入（也可以任意目录中）
/**
* @OA\SecurityScheme(
* type="apiKey",
* in="query",
* securityScheme="api_key",
* name="api_key"
* )
*/
在接口中添加
security={{"api_key": {}}},
这时，swagger Ui 会出现一个锁一样的东西
可以输入自己的token，请求的时候会带上token
可以结合 Laravel 的自带token验证，可以参考之前写的文章 Laravel guard 菊花守卫者
更多使用方法可以查看官网例子： https://github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0
