README

JsonApiBundle For Symfony

JsonApiBundle 是一个 Symfony 扩展包。它是使用 JsonApi 通过 woohoolabs/yin 库生成 API 的最快方式。

安装

安装 symfony

composer create-project symfony/skeleton YOUR_PROJECT

安装 maker 扩展包

composer require symfony/maker-bundle phootwork/collection --dev

安装扩展包

composer require paknahad/jsonapi-bundle

将以下行添加到 config/bundles.php

Paknahad\JsonApiBundle\JsonApiBundle::class => ['all' => true],

使用方法

使用以下命令逐个生成实体

bin/console make:entity

例如，Book 和 Author 实体如下

class Book
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=255)
     */
    private $title;

    /**
     * @ORM\Column(type="string", length=20, nullable=true)
     */
    private $isbn;

    /**
     * @ORM\ManyToMany(targetEntity="App\Entity\Author", inversedBy="books")
     */
    private $authors;
 
    ...

class Author
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=255)
     * @Assert\NotBlank()
     * @Assert\Length(min=3)
     */
    private $name;

    /**
     * @ORM\ManyToMany(targetEntity="App\Entity\Book", mappedBy="authors")
     */
    private $books;
 
    ...

生成 CRUD API
```
bin/console make:api
```
您可以在以下路径中找到生成的 "collections"，并在其中找到 postman 和 swagger，然后测试 API
```
collection/postman.json
collection/swagger.yaml
```

功能

分页

http://example.com/books?page[number]=5&page[size]=30

排序

按名称字段升序： http://example.com/books?sort=name
按名称字段降序： http://example.com/books?sort=-name
多个字段： http://example.com/books?sort=city,-name
关系字段： http://example.com/books?sort=author.name

关系

http://example.com/books?include=authors

多个关系

http://example.com/books?include=authors.phones,publishers

搜索

由于 JSON API 规范没有明确指定如何进行过滤，因此可以使用不同的过滤方法。每种方法都附带一个 Finder 服务。每个注册的 Finder 都可以添加条件到搜索查询中。如果您注册了多个 Finder，它们都将同时激活。这使得您的 API 能够支持多种过滤方法。

基本 Finder。

此库包含一个基本的 Finder，提供简单的过滤功能。

此请求将返回所有作者名字以 "hamid" 开头的书籍。

http://example.com/books?filter[authors.name]=hamid%

以下行有附加条件：标题中包含 "php" 的书籍。

http://example.com/books?filter[title]=%php%&filter[authors.name]=hamid%

其他 Finder

目前以下 Finder 通过其他扩展包提供

mnugter/jsonapi-rql-finder-bundle - 基于 RQL 的 Finder
paknahad-jsonapi-querifier-bundle - 基于 Querifier 的 Finder

创建自定义 Finder

Finder 可以通过服务定义中的服务标签进行注册。必须将标签 paknahad.json_api.finder 添加到服务，以便注册 Finder。

示例

<service class="Paknahad\JsonApiBundle\Helper\Filter\Finder" id="paknahad_json_api.helper_filter.finder">
    <tag name="paknahad.json_api.finder" />
</service>

每个 Finder 必须实现 Paknahad\JsonApiBundle\Helper\Filter\FinderInterface 接口。

验证

验证关联时的错误

{
    "jsonapi": {
        "version": "1.0"
    },
    "errors": [
        {
            "detail": "Invalid value for this relation",
            "source": {
                "pointer": "/data/relationships/authors",
                "parameter": "1"
            }
        }
    ]
}

如果您在实体上定义了验证器，请验证属性。

{
    "jsonapi": {
        "version": "1.0"
    },
    "errors": [
        {
            "detail": "This value is too short. It should have 3 characters or more.",
            "source": {
                "pointer": "/data/attributes/name",
                "parameter": "h"
            }
        }
    ]
}

错误处理器

所有错误，例如

内部服务器错误 (500)
未找到 (404)
拒绝访问 (403)

有如下响应

{
    "meta": {
        "code": 0,
        "message": "No route found for \"GET /book\"",
        "file": "/var/www/vendor/symfony/http-kernel/EventListener/RouterListener.php",
        "line": 139,
        "trace": [
            {
                "file": "/var/www/vendor/symfony/event-dispatcher/EventDispatcher.php",
                "line": 212,
                "function": "onKernelRequest"
            },
            {
                "file": "/var/www/vendor/symfony/event-dispatcher/EventDispatcher.php",
                "line": 44,
                "function": "doDispatch"
            },
            {
                "file": "/var/www/vendor/symfony/http-kernel/HttpKernel.php",
                "line": 125,
                "function": "dispatch"
            },
            {
                "file": "/var/www/vendor/symfony/http-kernel/HttpKernel.php",
                "line": 66,
                "function": "handleRaw"
            },
            {
                "file": "/var/www/vendor/symfony/http-kernel/Kernel.php",
                "line": 188,
                "function": "handle"
            },
            {
                "file": "/var/www/public/index.php",
                "line": 37,
                "function": "handle"
            }
        ]
    },
    "links": {
        "self": "/book"
    },
    "errors": [
        {
            "status": "404",
            "code": "NO_ROUTE_FOUND_FOR_\"GET_/BOOK\"",
            "title": "No route found for \"GET /book\""
        }
    ]
}

NOTICE：仅在开发环境中填充 "meta" 字段。

bornfight / jsonapi-bundle

维护者

详细信息