README

该工具包用于快速开发API，无需编写样板代码

该工具包的主要目的是处理DTO：序列化、反序列化和验证。它不涉及数据库和ORM。

该工具包解决的问题

• 将请求体从JSON反序列化为对象或对象数组
• 验证反序列化结果
• 将响应序列化为JSON
• 将异常序列化为JSON
• 从查询字符串中提取类型值
• 生成API文档

安装

composer require condenast-ru/basic-api-bundle

然后在 bundles.php 文件中启用此工具包

<?php declare(strict_types=1);
# config/bundles.php

return [
    # ...
    Condenast\BasicApiBundle\CondenastBasicApiBundle::class => ['all' => true],
];

它是如何工作的？

该工具包基于symfony内核事件订阅者，它们完成大部分工作。API操作通过控制器中的注解进行配置。注解的值写入请求属性，然后由订阅者使用。symfony/serializer 用于序列化和反序列化，symfony/validator 用于验证，nelmio/api-doc-bundle 用于API文档生成。

用法

API

• 根据 symfony/serializer 文档描述如何序列化和反序列化您的对象
• 根据 symfony/validator 文档描述您对象的验证规则
• 使用此工具包提供的注解配置您的控制器操作

示例

<?php declare(strict_types=1);

use Condenast\BasicApiBundle\Annotation as Api;
use Condenast\BasicApiBundle\Request\QueryParamBag;
use Condenast\BasicApiBundle\Response\Payload;
use Condenast\BasicApiBundle\Tests\Fixtures\App\DTO\Article;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Validator\Constraints as Assert;

class ArticleController
{
    /**
     * Create article
     *
     * @OA\Response( # Response description, for an API documentation only
     *     response=201,
     *     description="Created article",
     *     @OA\JsonContent(
     *         type="object",
     *         ref=@Nelmio\Model(type=Article::class, groups={"article.read"})
     *     )
     * )
     */
    #[Route(path: "/articles", name: "app.articles.post", methods: ["POST"])]
    #[Api\Resource("Article")] # Resource name used to group actions in API documentation
    #[Api\Deserialization(
        argument: "articles", # The argument of the controller method, the result of deserialization will be passed there
        type: Article::class, # The type of deserialization, such as Article or Article [] for an array of articles
        context: ["groups" => "article.write"], # Deserialization context,
        requestAttributes: ["id" => "id"] # Request attributes to assign their values to the properties of the deserialized object
                                          # It can be useful when, for example, in an edit action you deserialize the DTO, and the identifier of the entity is in the url
    )]
    #[Api\Validation(groups: ["article.write"])] # Validation groups
    #[Api\QueryParam(
        name: "tags", # The name by which the parameter will be available in the QueryParamBag
        path: "extra.tags", # The path to the parameter in the request, if not specified, will be equal to the name.
        isArray: true, # Whether the parameter is an array
        constraints: [ # Validation constraints
            new Assert\Length(min=2),
        ],
        default: [], # Default parameter value
                     # If not specified, then null or an empty array, depending on whether the parameter is declared as an array
                     # If the parameter value does not meet the requirements, the default value will be returned
        description: "Tags to associate with", # Description, for an API documentation only
        format: "uuid" # Format, for an API documentation only
    )]
    public function postArticle(Article $article, QueryParamBag $query): Payload
    {
        $tags = $query->get('tags');
    
        return new Payload($article, 201, ['groups' => 'article.read']);
    }
}

CORS

该工具包不包含任何关于CORS的内容，如果需要，请使用 nelmio/cors-bundle。

API文档

安装 nelmio/api-doc-bundle 和 symfony/twig-bundle，并按照文档进行配置，工具包描述符将向文档中添加它们从操作中可以学到的一切。任何缺失的内容都可以通过控制器中的注解添加，如 nelmio/api-doc-bundle 的文档中所述。

开发

要运行用于开发和调试的测试应用程序的Web服务器，请确保已安装Symfony CLI并运行 make server 命令。测试应用程序代码位于 tests/Fixtures/App 目录中。

测试

要运行测试，请使用 make tests 命令。