README

从 Open Api 规范文件生成 Laravel 应用程序代码

安装

您可以通过 composer 安装此包

composer require ensi/laravel-openapi-server-generator --dev

使用以下命令发布配置文件

php artisan vendor:publish --provider="Ensi\LaravelOpenApiServerGenerator\LaravelOpenApiServerGeneratorServiceProvider"

并配置所有选项。

从版本 0.x.x 迁移

删除 config/openapi-server-generator.php，使用上述命令重新发布，并重新创建所需的配置。

版本兼容性

基本用法

运行 php artisan openapi:generate-server。它将从您的 OAS3 文件生成所有配置的实体。
使用 php artisan openapi:generate-server -e routes,enums 覆盖 default_entities_to_generate 配置
使输出更详细： php artisan openapi:generate-server -v

覆盖模板

您还可以根据需要调整文件模板。

1. 在此存储库的 templates 目录中找到所需的模板；
2. 将其复制到您的应用程序内部的 resources/openapi-server-generator/templates 目录，或通过 extra_templates_path 选项配置包以使用另一个目录；
3. 更改所需的内容。

现有实体和生成器

'routes' => RoutesGenerator::class

为 oas3->paths 中的每个端点生成 Laravel 路由文件（route.php）
以下 扩展属性 被此生成器使用

x-lg-handler: '\App\Http\Controllers\CustomersController@create' // Optional. Path is ignored if this field is empty. You can use :: instead of @ if you want
x-lg-route-name: 'createCustomer' // Optional. Translates to `->name('createCustomer')`
x-lg-middleware: '\App\Http\Middleware\Authenticate::class,web'  // Optional. Translates to `->middleware([\App\Http\Middleware\Authenticate::class, 'web'])`
x-lg-without-middleware: '\App\Http\Middleware\Authenticate::class,web'  // Optional. Translates to `->withoutMiddleware([\App\Http\Middleware\Authenticate::class, 'web'])`

route.php 文件在每个生成过程中都会被覆盖。
您应该像这样将其包含在您的主路由文件中

$generatedRoutes = __DIR__ . "/OpenApiGenerated/routes.php";
if (file_exists($generatedRoutes)) { // prevents your app and artisan from breaking if there is no autogenerated route file for some reason.
    require $generatedRoutes;
}

'controllers' => ControllersGenerator::class

为 x-lg-handler 中指定的每个不存在的类生成控制器类
支持可调用的控制器。
如果多个 openapi 路径指向一个控制器/处理程序中的多个方法，则生成的类包括所有这些方法。
如果类已存在，则不会覆盖。
控制器类在生成后应进行修改。

'requests' => RequestsGenerator::class

为 DELETE、PATCH、POST、PUT 路径生成 Laravel 表单请求
目标必须配置为数组作为命名空间，而不是字符串。
例如。

'requests' => [
    'namespace' => ["Controllers" => "Requests"]
],

这意味着 "获取处理程序（x-lg-handler）命名空间，并在其中将控制器替换为请求"
表单请求类在生成后应进行修改。您可以将它视为使用 php artisan make:request FooRequest 生成的模板。
如果文件已存在，则不会在每个生成过程中覆盖。

表单请求类名为 ucFirst(operationId)。您可以使用 x-lg-request-class-name 覆盖它。
您可以使用 x-lg-skip-request-generation: true 指令跳过为给定路由生成表单请求。

在生成请求时，会自动生成 Laravel 验证规则，用于请求字段。
验证规则基于字段类型和必填字段生成。
对于应仅取某些枚举值的字段，您必须指定 x-lg-enum-class 选项。例如： x-lg-enum-class: 'CustomerGenderEnum'。

'enums' => EnumsGenerator::class

仅针对 oas3->components->schemas 中列出的枚举生成 Enum 类
您需要在每个枚举模式中指定 x-enum-varnames 字段。这些值用于枚举常量的名称。
在生成之前清除目标目录，以确保删除所有未使用的枚举类。
枚举生成器目前不支持 allOf、anyOf 和 oneOf。

'pest_tests' => PestTestsGenerator::class

为每个 x-lg-handler 生成 Pest 测试文件。
您可以使用 x-lg-skip-tests-generation: true 来排除 oas3 路径的测试生成。
如果测试文件已存在，则不会覆盖。
测试文件类在生成后可以进行修改。

'resources' => ResourcesGenerator::class

为 x-lg-handler 生成资源文件。
资源属性相对于响应中的字段生成，该字段可以在配置中设置。

'resources' => [
    'response_key' => 'data'
],

您还可以指定资源的 response_key：在对象中添加 x-lg-resource-response-key: data。
在指定 response_key 时，可以使用“点”语法来指定嵌套，例如 data.field。
您可以在路由中使用 x-lg-skip-resource-generation: true 来排除资源生成。
您可以在资源对象或属性对象中使用 x-lg-resource-class-name: FooResource 来重命名资源类。
如果资源文件已存在，则不会覆盖。
资源文件包含根据规范设置的一组字段。您还需要指定 mixin DocBlock 来自动完成资源。

'policies' => PoliciesGenerator::class

为路由生成 Laravel 策略。目的地必须配置为数组命名空间而不是字符串。例如

'policies' => [
    'namespace' => ["Controllers" => "Policies"]
],

• 路径必须包含 403 响应，否则不会生成策略。
• 您可以在路由中使用 x-lg-skip-policy-generation: true 来排除策略生成。
• 如果策略文件已存在，则不会覆盖。

贡献

有关详细信息，请参阅 CONTRIBUTING。

测试

1. composer install
2. composer test

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅 我们的安全策略。

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件。