预期学习目标
- Laravel官方推荐的几本书
- 关键文档记录
- 项目搭建
- 学习要点
- 源码学习
基本要点
路由的区别
Laravel 的路由不同与 ThinkPHP 的默认路由规则, Laravel 需要定义控制器路由
查看路由定义情况 : php artisan route:list +--------+----------+-----+------+---------+------------+| Domain | Method | URI | Name | Action | Middleware |+--------+----------+-----+------+---------+------------+| | GET|HEAD | / | | Closure | web |+--------+----------+-----+------+---------+------------+
拓展
- 下载项目
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 --helpUsage: 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
- 下载项目
git clone https://github.com/swagger-api/swagger-ui.git
- 主要文件
需要用到的只有 dist 这个文件夹,可以单独部署,也可以放在 public 文件夹内,为了避免读取元数据的跨域问题,将元数据保存在同个位置
# 安装 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 - 下载项目
https://github.com/swagger-api/swagger-editor.git
- 生成服务端代码
Swagger 2.0版本可以生成 PHP 后端代码, OpenAPI 3.0.0 版本暂不支持