README

简介

此包提供了一种方便的方式，可以根据 YAML 格式的 OpenAPI 规范生成 Laravel 路由、请求和控制器。

动机

例如，我们有一个 openapi.yaml

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      #...
      x-og-route-name: listUsers
      x-og-controller: App\Http\Controllers\UsersController@index
      x-og-skip-request: true
      x-og-middlewares: auth
      x-og-skip-resource: false
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      ...
      x-og-route-name: createUser
      x-og-controller: App\Http\Controllers\UsersController@store
      x-og-skip-request: false
      x-og-skip-resource: false
      x-og-middlewares: auth,admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
  /users/{userId}:
    put:
      ...
      x-og-generation: true
      x-og-route-name: updateUser
      x-og-controller: App\Http\Controllers\UsersController@update
      x-og-skip-request: false
      x-og-middlewares: auth,admin
      x-og-skip-resource: false
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user to update.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
          pattern: '^[a-zA-Z0-9_-]{3,16}$'
        email:
          type: string
          format: email
          maxLength: 30
      required:
        - username
        - email

运行 php artisan openapi:generate-code 命令后，该包将为您生成以下代码。

routes/openapi-codegen.php

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\UsersController;

Route::get('users', [UsersController::class, 'index'])->name('listUsers')->middleware(['auth']);
Route::post('users', [UsersController::class, 'store'])->name('createUser')->middleware(['auth', 'admin']);
Route::put('users/{userId}', [UsersController::class, 'update'])->name('updateUser')->middleware(['auth', 'admin']);

app/Http/Controllers/UsersController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use App\Http\Resources\UsersResource;
use App\Http\Requests\StoreUsersRequest;
use App\Http\Requests\UpdateUsersRequest;

class UsersController
{
    public function index(): JsonResponse
    {
        // return UsersResource();
    }

    public function store(StoreUsersRequest $request): JsonResponse
    {
        // return UsersResource();
    }

    public function update(int $userId, UpdateUsersRequest $request): JsonResponse
    {
        // return UsersResource();
    }

}

app/Http/Requests/StoreUsersRequest.php

<?php

namespace App\Http\Requests;

use Illuminate\Http\Request;

class StoreUsersRequest extends Request
{
    public function rules(): array
    {
        return [
            'username' => ['required', 'string', 'regex:/^[a-zA-Z0-9_-]{3,16}$/'],
            'email' => ['required', 'string', 'email', 'max:30'],
        ];
    }
}

app/Http/Requests/UpdateUsersRequest.php

<?php

namespace App\Http\Requests;

use Illuminate\Http\Request;

class UpdateUsersRequest extends Request
{
    public function rules(): array
    {
        return [
            'username' => ['required', 'string', 'regex:/^[a-zA-Z0-9_-]{3,16}$/'],
            'email' => ['required', 'string', 'email', 'max:30'],
        ];
    }
}

app/Http/Resources/UsersResource.php

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UsersResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'username' => $this->username,
            'email' => $this->email,
        ];
    }
}

安装

要安装此包，您可以使用 Composer

composer require --dev laravel-openapi/codegen

配置

安装包后，您需要配置它以满足项目的需求。此包提供各种配置选项来自定义代码生成过程。

发布配置

php artisan vendor:publish --provider="LaravelOpenapi\Codegen\LaravelOpenapiCodegenProvider"

此命令将在您的 Laravel 应用程序的 config 目录中创建一个 openapi-codegen.php 文件。

配置选项

在 openapi-codegen.php 配置文件中，您将找到以下选项

• api_docs_url：指定 OpenAPI 文档可访问的 URL。此 URL 应指向您的 OpenAPI 规范文件的位置。
• entities：定义要执行代码生成的实体。您可以通过将它们添加到此数组中来指定应该生成哪些实体。支持的实体包括

  • route：根据 OpenAPI 路径生成 Laravel 路由。

  • request：根据 OpenAPI 请求体生成请求类。

  • resource：为 API 响应生成资源类。

  • controller：为处理 API 请求生成控制器。

    默认情况下，将生成所有支持的实体。要排除特定实体，只需从该数组中移除它们即可。

• paths：指定应用程序中使用的额外路径。目前，仅提供 routes_file 选项，用于定义生成 OpenAPI 路由的文件路径。

用法

生成代码

要从 OpenAPI YAML 文件生成 Laravel 代码，您可以使用以下 Artisan 命令

php artisan openapi:generate-code

此命令将根据提供的 OpenAPI YAML 文件生成 Laravel 路由、请求、资源和控制器。

贡献

我欢迎社区的贡献！如果您有任何改进的想法或发现任何问题，请随时在 GitHub 上打开问题或提交拉取请求。

许可证

此包是开源软件，许可协议为 MIT 许可证。

支持

如果您在使用包时遇到任何问题或有任何疑问，请通过电子邮件（safarumarov@gmail.com）或 GitHub 问题与我们联系。