PHP 框架学习（二）：Laravel

zuixinyan

2019-06-29

预期学习目标

Laravel官方推荐的几本书
关键文档记录
项目搭建
学习要点
源码学习

基本要点

命令行工具

# 在默认路径下创建路由
php artisan make:controller Controller

# 在默认路径下创建路由等价与以下命令
php artisan make:controller App\\Http\\Controllers\\Controller

# 在默认路径下创建路由等价与以下命令
php artisan make:controller 'App\Http\Controllers\Controller'

# 自定义命名空间
php artisan make:controller 'App\Api\Auth\Controller'

路由的设置

Laravel 的路由不同与 ThinkPHP 的默认路由规则, Laravel 需要定义控制器路由

查看路由定义情况 : php artisan route:list

+--------+----------+-----+------+---------+------------+
| Domain | Method   | URI | Name | Action  | Middleware |
+--------+----------+-----+------+---------+------------+
|        | GET|HEAD | /   |      | Closure | web        |
+--------+----------+-----+------+---------+------------+

数据的迁移

# 数据构造器

php artisan make:seeder DataSeeder

安装拓展

Swagger-php

下载项目

Swagger-php 提供的 openapi 可以在 CLI (命令行) 中执行生成元数据,全局安装的意义就在此,可以直接使用openapi 而不是全路径

# 直接下载仓库代码
https://github.com/swagger-api/swagger-editor.git

# 使用包管理工具安装
composer require zircote/swagger-php

# 指定版本
composer require zircote/swagger-php 2.0.13

# 使用包管理工具安装在全局
composer global require zircote/swagger-php

# 使用包管理工具安装
composer install

元数据的概念

元数据（Metadata），又称中介数据、中继数据，为描述数据的数据（data about data），主要是描述数据属性（property）的信息，用来支持如指示存储位置、历史数据、资源查找、文件记录等功能。

将代码注释生转化为元数据

# openapi的用法
.\vendor\bin\openapi --help

Usage: openapi [--option value] [/path/to/project ...]

Options:
  --output (-o)     Path to store the generated documentation.
                    ex: --output openapi.yaml
  --exclude (-e)    Exclude path(s).
                    ex: --exclude vendor,library/Zend
  --bootstrap (-b)  Bootstrap a php file for defining constants, etc.
                    ex: --bootstrap config/constants.php
  --processor       Register an additional processor.
  --format          Force yaml or json.
  --debug           Show additional error information.
  --help (-h)       Display this help message.

# 生成指定文件的元数据(yaml格式)到指定位置
vendor\bin\openapi vendor\zircote\swagger-php\Examples\ -o public\swagger-ui\dist\

# 生成指定文件的元数据(json格式)到指定位置
vendor\bin\openapi vendor\zircote\swagger-php\Examples\ -o public\swagger-ui\dist\ --format json

Swagger-ui

下载项目

git clone https://github.com/swagger-api/swagger-ui.git

主要文件

需要用到的只有 dist 这个文件夹,可以单独部署,也可以放在 public 文件夹内,为了避免读取元数据的跨域问题,将元数据保存在同个位置

PHP 框架学习（二）：Laravel

将本地元数据转化为API文档

# 安装 http-server 环境
npm install -g http-server

# 开启服务并允许跨域资源共享
http-server --cors

# 浏览器打开 Swagger-UI 的界面
http://127.0.0.1:8080/ltf/public/swagger-ui/dist/

# 将本地元数据转化为API文档
http://127.0.0.1:8080/ltf/public/swagger-ui/dist/openapi.yaml

PHP 框架学习（二）：Laravel

上图划线位置根据输入的元数据文件路径生成API文档,多个项目时便是在这里根据元数据文件路径切换API文档

格式验证

Swagger-UI 默认会将元数据传给 swagger.io 进行格式验证，由于是公司内部项目所以关闭验证功能

# 在 index.html 中添加 validatorUrl: null 关闭验证功能

  const ui = SwaggerUIBundle({
    validatorUrl: null,
    url: "openapi.yaml",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

默认元数据读取路径

如上代码中的 url: "openapi.yaml",原本是 https://petstore.swagger.io/v2/swagger.json 官方提供的示例

自动更新文档

# 创建一个控制器
php artisan make:controller SwaggerController

# 添加注释以及实现扫描功能
/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
public function scan()
{
    $openapi = \OpenApi\scan(__DIR__);
    header('Content-Type: application/x-yaml');
    return $openapi->toJson();
}
    
# 注册路由
Route::get('scan', 'SwaggerController@scan');

# 访问页面
http://www.ltf.com/scan

# 将路径写入到index.html文件中实现扫描功能
url: "http://www.ltf.com/scan"

# 访问API文档页面即可得到最新文档
http://www.ltf.com/doc