README

1. 通过 Composer 安装

$ composer require sitesoft/laravel-apis

2. 在 config/app.php 文件中添加到 providers

Sitesoft\LaravelApis\ApisServiceProvider::class

3. 为了允许所有 API 请求的 CORS，请在 app/Http/Kernel.php 文件中的 $middlewareGroups 中添加 HandleCors 中间件：(见 "支持 Cross-Origin Resource Sharing (CORS)" 部分)

protected $middlewareGroups = [
    'web' => [
       // ...
    ],

    'api' => [
        // ...
        \Barryvdh\Cors\HandleCors::class,
    ],
];

4. 发布包中的 apis.php 配置文件

$ php artisan vendor:publish --provider="Sitesoft\LaravelApis\ApisServiceProvider"

使用方法

在 Sitesoft APIS 上添加新项目

$ php artisan apis:create-project <name> <version> <url> --path=<path>

其中

• <name> - 新项目的名称（可以使用西里尔字母）
• <version> - API 版本（仅数字）
• <url> - API 的基本 URL（必须以 http 或 https 开头，例如 http://test.com/api）
• <path> - API 目录的路径（相对于 app/Http/Controllers/ 文件夹，不是必须的，默认为 Api）

例如，如果您的 API 文件位于 app/Http/Controllers/Api/v1 文件夹中，则命令如下

$ php artisan apis:create-project MyApi 1 http://test.com/api --path="Api/v1"

该命令将执行以下操作

1. 生成令牌并将其写入 config/apis.php 文件
2. 将 SwaggerController.php 添加到 app/Http/Controllers/Api/v1/
3. 将 Swagger 路由添加到 routes/api.php 文件
4. 向 Sitesoft APIS 发送请求以添加新项目
5. 在配置文件 apis.php 中添加生成 swagger.json 的路径

swagger.json 的生成

此文件由库 swagger-php 根据每个 API 版本独立生成。

$ php artisan swaggen

生成文件夹设置在配置文件 config/apis.php 中的 paths 参数中。Swagger 将扫描这些文件夹并在每个文件夹中创建自己的 swagger.json。

每个这样的文件都应该可以从外部访问，为此，在 apis:create-project 和 apis:add-version 命令中指定的 <path> 路径处创建 SwaggerController.php 文件

支持 Cross-Origin Resource Sharing (CORS)

您的 API 方法必须返回 Access-Control-Allow-Origin 标头，以便能够在 Sitesoft APIS 中查看响应。

为了支持 CORS，使用 barryvdh/laravel-cors，要使用它，只需执行 安装 部分的第 3 点。或者，您可以为某些路由启用 CORS

Route::group(['middleware' => 'cors'], function(){
    Route::get('/create', 'Api\CreateController@index');
    Route::post('/add', 'Api\AddController@index');
    Route::delete('/delete', 'Api\DeleteController@index');
});

或者这样

Route::get('/create', 'Api\CreateController@index')->middleware('cors');
Route::post('/add', 'Api\AddController@index')->middleware('cors);
Route::delete('/delete', 'Api\DeleteController@index')->middleware('cors');

laravel-cors 模块还可以配置 https://github.com/barryvdh/laravel-cors#configuration

在 Sitesoft APIS 上添加新版本

$ php artisan apis:add-version <version> <url> --path=<path>

其中

• <version> - API 版本（仅数字）
• <url> - API 的基本 URL（必须以 http 或 https 开头，例如 http://test.com/api/v2）
• <path> - API 目录的路径（相对于 app/Http/Controllers/ 文件夹，不是必须的，默认为 Api_v<version>）

例如，如果您的 API 新版本文件位于 app/Http/Controllers/Api/v2 文件夹中（相对于项目根目录），则命令如下

$ php artisan apis:add-version 2 http://test.com/api/v2 --path="Api/v2"

该命令将执行以下操作

1. 将 SwaggerController.php 添加到 app/Http/Controllers/Api/v2/
2. 将 Swagger 路由添加到 routes/api.php 文件
3. 向 Sitesoft APIS 发送请求以添加新项目版本
4. 在配置文件 apis.php 中添加生成 swagger.json 的路径