README

Ogen代表OpenAPI Generator，是一个从OpenAPI规范YAML文件生成Symfony捆绑包的工具。捆绑包是一个实现指定API的服务器占位符：它自动处理所有路由以及DTOs及其验证的序列化和反序列化。然后，您需要通过实现捆绑包定义的接口来连接领域行为。

用法

要使用Ogen，您首先需要将此供应商的最新版本安装到项目中

make composer-bash
composer require --dev zolteam/ogen:^1.0
exit

然后，在Makefile中添加一个目标

ogen:
	rm -rf symfony/openapi/invoicing/bundle/*
	wget -O symfony/openapi/invoicing/openapi.yaml https://stoplight.io/api/v1/projects/bfav-zol/zol-skeleton/nodes/zol-skeleton.yaml
	@$(RUNNER_DOCKER_EXEC) 'vendor/bin/ogen InvoicingOpenApiServer Zol\\Invoicing\\OpenApiServer zol/invoicing-openapi-server /var/www/html/openapi/invoicing/openapi.yaml /var/www/html/openapi/invoicing/bundle'
	make cc

• 将所有symfony/openapi/invoicing/bundle替换为您想要生成捆绑包代码的文件夹的路径。
• 将所有symfony/openapi/invoicing/openapi.yaml替换为您想要OpenApi规范YAML文件的路径。
• 将https://stoplight.io/api/v1/projects/bfav-zol/zol-skeleton/nodes/zol-skeleton.yaml替换为您OpenApi规范YAML文件的URL（在这个例子中，我们使用stoplight.io作为我们的规范编辑器）。
• 将InvoicingOpenApiServer替换为您想要给捆绑包取的名字。
• 将Zol\\Invoicing\\OpenApiServer替换为您想要捆绑包类所在的命名空间。
• 将zol/invoicing-openapi-server替换为您想要捆绑包的composer包名称。

然后，运行目标

make ogen

从现在开始，您可以在更新OpenAPI规范时通过重新执行前面的命令随时覆盖捆绑包。您永远不应该修改捆绑包中的任何文件，因为它们将在每次重新生成捆绑包时被覆盖。

捆绑包现在已生成，需要配置。首先将捆绑包目录添加到项目的composer.json中作为仓库

"repositories": [
    {
        "type": "path",
        "url": "openapi/invoicing/bundle"
    }
]

然后您可以使用捆绑包

make composer-bash
composer require zol/invoicing-openapi-server:dev-main
composer update
exit

接下来，将捆绑包添加到symfony/config/bundles.php文件中

<?php

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
    Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
    Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
    \Zol\Invoicing\OpenApiServer\InvoicingOpenApiServerBundle::class => ['all' => true], // <-- Here
];

然后，在symfony/config/routes.yaml文件中将捆绑包路由添加到您选择的任何前缀下

parazol:
  resource: '@InvoicingOpenApiServerBundle/config/routes.yaml'
  prefix: 'api'

现在，您必须实现您在捆绑包中找到的所有接口，即所有src/Api/<TagName>/<TagName>Handler.php和所有src/Format/<FormatName>Definition.php。一旦实现，您必须将它们声明为服务并在services.yaml文件中适当地标记它们。以下是一个示例

<?php

// symfony/src/Zol/Invoicing/Presentation/Client/ClientHandler.php

namespace App\Zol\Invoicing\Presentation\Client;

use Zol\Invoicing\OpenApiServer\Api\Client\GetClients200ApplicationJsonResponse;

class ClientHandler implements \Zol\Invoicing\OpenApiServer\Api\Client\ClientHandler
{
    // ...
}

<?php

// symfony/src/Zol/Invoicing/Presentation/UuidDefinition.php

namespace App\Zol\Invoicing\Presentation;

class UuidDefinition implements \Zol\Invoicing\OpenApiServer\Format\UuidDefinition
{
    public function validate(mixed $value): array
    {
        // ...
    }
}

# symfony/config/services.yaml

### Handlers ###

App\Zol\Invoicing\Presentation\Client\ClientHandler:
    tags:
        - { name: "invoicing_open_api_server.handler", controller: "client" }

### Format Definitions ###

App\Zol\Invoicing\Presentation\UuidDefinition:
    tags:
        - { name: "invoicing_open_api_server.format_definition", format: "uuid" }

就是这样，您现在可以通过调用您的端点进行测试！

故障排除

我的所有端点都在DefaultHandler下列出

如果您标记了操作，它将列在

我的端点既不在路由也不在生成的处理器中列出

确保您在端点规范中声明了至少一个包含非空内容的响应。例如，您始终可以指定一个400响应，即使您在实现中永远不会返回它。

我的处理器的名称没有意义

操作名称用于生成它们，所以使它们清晰简单，例如“get-client”。