README

此包是一个通用 REST API，可以轻松使用您的 Doctrine 实体创建和配置您的 API 资源。

设置

$ composer req nbo/restapibundle

文档

入门

首先，您需要组合您的 API。在您的项目中添加 config/packages/rest_api.yml 配置。

以下是一个简单 REST API 的示例，包含 "user" 和 "page" 资源。

rest_api:
  default_limit: 10
  default_offset: 0
  default_order: {'id':'desc'}
  resources:
    user:
      classname: 'App\Entity\User'
      methods:
        get:
          authenticated: true
          roles: ['ROLE_ADMIN']
        post:
          authenticated: true
          roles: ['ROLE_ADMIN']
        put:
          authenticated: true
          roles: ['ROLE_ADMIN']
        delete:
          authenticated: true
          roles: ['ROLE_ADMIN']
    page:
      classname: 'App\Entity\Page'
      methods:
        get: ~
        post:
          authenticated: true
          roles: ['ROLE_CMS']
        put:
          authenticated: true
          roles: ['ROLE_CMS']
        delete:
          authenticated: true
          roles: ['ROLE_CMS']

在这个示例中，所有资源端点都需要一个经过身份验证的用户，并且具有特定的角色，除了公开的 GET /page。

用例

需要认证用户的端点

要限制端点仅允许认证用户，无论其角色如何，只需使用 authenticated 选项。

需要认证用户和特定角色的端点

要限制端点仅允许具有一个或多个特定角色的认证用户，只需使用 roles 数组选项和所需的角色。

用户作用域资源

有时，您需要将特定资源作用域在用户级别，其中用户只能查看他们自己的资源。使用 owner_restricted 选项即可做到这一点。

公开端点

默认情况下，如果没有选项，端点是公开的。不需要身份验证。

更新您的 Doctrine 实体

下一步是将您的 Doctrine 实体转换为 API 资源。

以下是将用户实体转换为 API 资源的示例。

<?php

namespace App\Entity;

use App\Entity\Traits\TimestampableEntity;
use Doctrine\ORM\Mapping as ORM;
use Gedmo\SoftDeleteable\Traits\SoftDeleteableEntity;
use Nbo\RestApiBundle\Annotations\Resource;
use Nbo\RestApiBundle\Entity\AbstractResource;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @Resource(name="user")
 * @ORM\Entity(repositoryClass="App\Repository\UserRepository")
 * @ORM\HasLifecycleCallbacks()
 */
class User extends AbstractResource implements UserInterface
{
    const ROLE_ADMIN = 'ROLE_ADMIN';

    use TimestampableEntity;
    use SoftDeleteableEntity;

    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     * @Groups("public")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=180, unique=true)
     * @Groups("public")
     */
    private $email;

    /**
     * @ORM\Column(type="string", length=180)
     * @Groups("public")
     */
    private $displayName;

    /**
     * @ORM\Column(type="json")
     * @Groups("public")
     */
    private $roles = [];

    /**
     * @var string The hashed password
     * @ORM\Column(type="string")
     * @Groups("private")
     */
    private $password;

    public function __toString()
    {
        return (string) $this->getDisplayName();
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getEmail(): ?string
    {
        return $this->email;
    }

    public function setEmail(string $email): self
    {
        $this->email = $email;

        return $this;
    }

    /**
     * @return string
     */
    public function getUsername(): string
    {
        return (string) $this->getEmail();
    }

    /**
     * @return mixed
     */
    public function getDisplayName(): ?string
    {
        return $this->displayName;
    }

    /**
     * @param mixed $displayName
     * @return User
     */
    public function setDisplayName($displayName = null)
    {
        $this->displayName = $displayName;
        return $this;
    }

    /**
     * @see UserInterface
     */
    public function getRoles(): array
    {
        $roles = $this->roles;
        $roles[] = 'ROLE_USER';

        return array_unique($roles);
    }

    public function setRoles(array $roles): self
    {
        $this->roles = $roles;
        return $this;
    }

    /**
     * @see UserInterface
     */
    public function getPassword(): string
    {
        return (string) $this->password;
    }

    public function setPassword(string $password): self
    {
        $this->password = $password;
        return $this;
    }

    /**
     * @see UserInterface
     */
    public function getSalt()
    {
    }

    /**
     * @see UserInterface
     */
    public function eraseCredentials()
    {
    }
}

这是一个在 Symfony 项目中的简单用户业务对象。要将其转换为 API 资源，您只需添加 @Resource(name="your_api_resource_name") 注解。

然后，您必须扩展 AbstractResource 或 AbstractTranslatableResource 抽象层。

在这个级别，API 响应是空的，要添加数据，您需要在要公开的实体类成员上添加 @Groups("public")。

就是这样，您的 "user" 资源 REST API 现在已经准备好了！具有 "ROLE_ADMIN" 角色的认证用户现在可以获取、创建、更新或删除 "http://yourdomain/api/user" 端点上的任何用户。

在未来不久，@Group() 注解组将变得更加灵活，允许根据认证用户的角色提供不同级别的资源属性访问。

筛选 API 资源

您可以使用 "q" 查询字符串参数使用以下筛选器筛选 API 资源

大于运算符

我们查询所有产品资源，价格大于 150

GET https://:8000/api/product?page=1&limit=50&count=1&q={"price":{">":150}}

小于运算符

我们查询所有产品资源，价格小于 150

GET https://:8000/api/product?page=1&limit=50&count=1&q={"price":{"<":150}}

等于运算符

我们查询所有产品资源，价格等于 150

GET https://:8000/api/product?page=1&limit=50&count=1&q={"price":{"=":150}}

不等于运算符

我们查询所有产品资源，颜色不同于黄色

GET https://:8000/api/product?page=1&limit=50&count=1&q={"color":{"!=":"yellow"}}

是空值运算符

我们查询所有产品资源，分类为空

GET https://:8000/api/product?page=1&limit=50&count=1&q={"category":{"IS NULL":"null"}}

不是空值运算符

我们查询所有产品资源，分类不为空

GET https://:8000/api/product?page=1&limit=50&count=1&q={"category":{"IS NOT NULL":"null"}}

LIKE 运算符

我们查询所有产品资源，名称以 "bag" 开头

GET https://:8000/api/product?page=1&limit=50&count=1&q={"name":{"LIKE":"bag%"}}

在此我们查询所有产品资源，名称以“bag”结尾

GET https://:8000/api/product?page=1&limit=50&count=1&q={"name":{"LIKE":"%bag"}}

在此我们查询所有产品资源，名称中包含“bag”

GET https://:8000/api/product?page=1&limit=50&count=1&q={"name":{"LIKE":"%bag%"}}

排序API资源

您可以使用“sort”查询参数，按照以下语法对一个或多个字段进行API资源排序。

GET https://:8000/api/media?page=1&limit=50&count=1&q={"platform":{"="52"}}&sort[updated]=desc&sort[otherfield]=asc

统计总API资源数量

为了构建客户端的分页系统，您需要知道针对特定请求有多少API资源可用。要统计特定请求的API资源，只需添加count查询参数。

GET https://:8000/api/todo?page=5&limit=10&count=1

API将在响应头中添加一个“Count”头，包含给定请求的资源数量。

可翻译资源

当您的业务对象需要支持i18n时，您可以使用带有地区参数的GET、POST和PUT操作。

GET https://:8000/api/blog?page=5&limit=10

成为

GET https://:8000/api/fr/blog?page=5&limit=10

要启用此行为，您需要安装stof/doctrine-extensions-bundle，并将您的Doctrine实体更新为扩展AbstractTranslatableResource层，并在可翻译实体字段上添加 * @Gedmo\Translatable() 注释。

stof/doctrine-extensions-bundle是官方支持的Doctrine扩展包，但未来的版本将允许任何Doctrine行为扩展。