使用 laravel-Swagger 编写接口文档

Swagger 文档管理

快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。

优势

通过代码注解定义文档，更容易保持代码文档的一致性

模型复用，减少文档冗余，带来更可靠的文档

提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口

支持权限认证，等功能

laravel Swagger 扩展

composer require darkaonline/l5-swagger

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

将会生成配置文件 l5-swagger.php，其中需要注意的配置项

routes.api 默认值为 api/documentation Swagger 文档系统访问路由

routes.docs Swagger 解析注释生成文档 JSON 文件的存储路径

paths.annotations 有效注释的路径配置，默认 base_path('app') 应用路径

generate_always 测试环境应该开启这个配置，每次访问都会自动解析注释生成最新的文档

swagger_version 这个默认为 2.0 , 建议修改为 3.0

下文所有的注释内容，需要存在于 paths.annotations 路径下。

接口版本

@OA\Info 定义接口版本，标题，描述，以及作者信息。

/**

* @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，将会对接口归类

/**

 * @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}

/**

 * @OA\Get(

 *   @OA\Parameter(

 *     name="user_id",

 *     in="path",

 *     required=true,

 *     description="用户 ID",

 *     @OA\Schema(

 *        type="string"

 *     )

 * )

 */

POST 提交表单，通常使用 application/json 方式，如，创建用户

@OA\Post

path=/users

/**

 *   @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")

/**

* @OA\Schema(

*      schema="UserModel",

*      required={"username", "age"},

*      @OA\Property(

*          property="username",

*          type="string",

*          description="用户名称"

*      ),

*      @OA\Property(

*          property="age",

*          type="int",

*          description="年龄"

*      )

* )

*/

Laravel-Swagger 会自动根据您的注释进行匹配

上传文件接口示例

定义一个接口，接收上传文件，并返回结果远程文件地址

接口定义：

/**

 * @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")

 *   )

 * )

 */

模型定义：

/**

* @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="文件扩展名"

*      )

* )

*/

需要权限认证的接口

一般对外网开放的接口，需要添加权限控制，Swagger 提供很好的支持

在 l5-swagger.php 配置文件中添加， crypt-token 定义请求头部必须添加 token 作为权限校验令牌。

'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".

   ],

]

接口注释中，添加对应的验证方式：

/**

 * security={

 *    {"crypt-token": {}}

 * },

 */

以上就是“使用 laravel-Swagger 编写接口文档”的详细内容，想要了解更多laravel教程欢迎关注编程学习网