使用 Laravel-Swagger 编写接口文档
Table of Contents
Swagger 文档管理
官方网站：https://swagger.io/
快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。
优势
- 通过代码注解定义文档，更容易保持代码文档的一致性
- 模型复用，减少文档冗余，带来更可靠的文档
- 提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口
- 支持权限认证，等功能
Laravel Swagger 扩展
扩展源代码地址：https://github.com/DarkaOnLine/L5-Swagger
12 |
composer require darkaonline/l5-swaggerphp artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" |
将会生成配置文件 l5-swagger.php，其中需要注意的配置项
routes.api默认值为api/documentationSwagger 文档系统访问路由routes.docsSwagger 解析注释生成文档 JSON 文件的存储路径paths.annotations有效注释的路径配置，默认base_path(‘app‘)应用路径generate_always测试环境应该开启这个配置，每次访问都会自动解析注释生成最新的文档swagger_version这个默认为 2.0 , 建议修改为 3.0
下文所有的注释内容，需要存在于 paths.annotations 路径下。
接口版本
@OA\Info 定义接口版本，标题，描述，已经作者信息。
1234567891011 |
/** * @OA\Info( * version="1.0", * title="用户管理", * description="用户模块接口", * @OA\Contact( * name="PHP 开发支持", * email="dreamhelingfeng@gmail.com" * ) * ) */ |
接口请求方式与请求路径
@OA\Get,@OA\Post 定义接口请求方式
示例：根据USER_ID请求用户详情信息 /api/users/{user_id}
接口分组配置：tags，将会对接口归类
123456789101112131415161718192021 |
/** * @OA\Get( * path="/api/users/{user_id}", * summary="根据 ID 获取用户信息", * tags={"用户管理"}, * @OA\Parameter( * name="user_id", * in="path", * required=true, * description="用户 ID", * @OA\Schema( * type="string" * ) * ), * @OA\Response( * response=200, * description="用户对象", * @OA\JsonContent(ref="#/components/schemas/UserModel") * ) * ) */
|
接口请求参数
通过 Swagger 可以定义三类参数，path,header,query
- path, 参数存在 endponit 中，如，/users/{user_id}
- header, 参数存在请求头部，如，token 用户校验令牌
- query, 请求参数带在请求URL上，如，/users?nickname={nickname}
123456789101112 |
/** * @OA\Get( * @OA\Parameter( * name="user_id", * in="path", * required=true, * description="用户 ID", * @OA\Schema( * type="string" * ) * ) */ |
POST 提交表单，通常使用 application/json 方式，如，创建用户
@OA\Post
path=/users
1234567891011 |
/** * @OA\RequestBody( * @OA\MediaType( * mediaType="application/json", * @OA\Schema(ref="#/components/schemas/UserModel"), * example={ * "username": "helingfeng", "age": "25" * } * ) * ) */
|
Schema 模型定义
上面的注释中，多次引用 @OA\Schema(ref="#/components/schemas/UserModel")
12345678910111213141516 |
/** * @OA\Schema( * schema="UserModel", * required={"username", "age"}, * @OA\Property( * property="username", * type="string", * description="用户名称" * ), * @OA\Property( * property="age", * type="int", * description="年龄" * ) * ) */
|
Laravel-Swagger 会自动根据您的注释进行匹配
上传文件接口示例
定义一个接口，接收上传文件，并返回结果远程文件地址
接口定义：
123456789101112131415161718192021222324252627282930 |
/** * @OA\Post( * path="/api/files/upload", * summary="文件上传", * tags={"文件上传"}, * @OA\RequestBody( * @OA\MediaType( * mediaType="multipart/form-data", * @OA\Schema( * required={"upload_file"}, * @OA\Property( * property="upload_file", * type="file", * description="上传文件" * ), * ), * ) * ), * @OA\Response( * response=200, * description="上传成功", * @OA\JsonContent(ref="#/components/schemas/UploadFileModel") * ), * @OA\Response( * response="default", * description="error", * @OA\JsonContent(ref="#/components/schemas/ErrorModel") * ) * ) */
|
模型定义：
123456789101112131415161718192021222324252627282930 |
/** * @OA\Schema( * schema="UploadFileModel", * @OA\Property( * property="file_name", * type="string", * description="文件名，不包含路径" * ), * @OA\Property( * property="file_path", * type="string", * description="文件路径" * ), * @OA\Property( * property="file_url", * type="string", * description="URL链接，用于展示" * ), * @OA\Property( * property="file_size", * type="string", * description="文件大小，单位B" * ), * @OA\Property( * property="extension", * type="string", * description="文件扩展名" * ) * ) */ |
访问 api/documentation 效果如图
try it out 上传文件操作结果
需要权限认证的接口
一般对外网开放的接口，需要添加权限控制，Swagger 提供很好的支持
在 l5-swagger.php 配置文件中添加， crypt-token 定义请求头部必须添加 token 作为权限校验令牌。
12345678910111213 |
‘security‘ => [ /* |-------------------------------------------------------------------------- | Examples of Security definitions |-------------------------------------------------------------------------- */ ‘crypt-token‘ => [ // Unique name of security ‘type‘ => ‘apiKey‘, // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2". ‘description‘ => ‘A short description for security scheme‘, ‘name‘ => ‘token‘, // The name of the header or query parameter to be used. ‘in‘ => ‘header‘, // The location of the API key. Valid values are "query" or "header". ],] |
接口注释中，添加对应的验证方式：
12345 |
/** * security={ * {"crypt-token": {}} * }, */
|
更多 Swagger3 定义字段描述，可以查看官方文档：https://swagger.io/specification/#parameterObject
原文地址：https://www.cnblogs.com/duanweishi/p/11113246.html
时间： 2024-10-09 06:27:10