预期学习目标
- 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
文件夹内,为了避免读取元数据
的跨域问题,将元数据
保存在同个位置
将本地元数据转化为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
上图划线位置根据输入的元数据
文件路径
生成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
Swagger-editor
- 下载项目
https://github.com/swagger-api/swagger-editor.git
- 生成服务端代码
Swagger 2.0版本可以生成 PHP 后端代码, OpenAPI 3.0.0 版本暂不支持
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。