README

此包提供了一些基于白宫标准生成API响应的工具，并为Laravel中的SnappMarket团队提供了一些定制。

💡 要从头开始，请阅读此文档。

安装

$ composer require snappmarket/api-responder

使用

以下别名已在包的主要服务提供者中注册。

ApiResponderResponse 对应 SnappMarket\ApiResponder\Facades\Response
ApiResponderErrors 对应 SnappMarket\ApiResponder\Facades\ErrorsRepository

在以下所有示例中，使用别名而不是完整命名空间。

注册错误

根据白宫标准，每个错误代码都应该指向一个错误实体。在API Responder中，您可以在ErrorsRepository类中注册错误及其信息，以便之后使用。

ApiResponderErrors::register(
     '40001',
     'Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here',
     'This is a message that can be passed along to end-users, if needed.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

注销错误

注销错误是一个常见问题。您可以使用以下代码来完成。

ApiResponderErrors::unregister('40001');

制作失败响应

根据白宫标准，失败响应应返回400或500响应。因此，我们有可用的两个方法来返回这些状态下的错误。

clientError()：此方法可以生成客户端错误的响应体。
```
ApiResponderResponse::clientError('40001');
```
serverError()：此方法可以生成服务器错误的响应体。
```
ApiResponderResponse::serverError('40001');
```

之后，我们还有一个可以手动指定状态的方法。

ApiResponderResponse::error('40001', 422);

在SnappMarket中，我们向响应JSON中添加了一个名为errors的对象。此字段可以包含详细错误。

替换

在注册错误信息时，您可以放置一些可替换的短语，以使其内容动态化。可替换的短语应从:开始。

ApiResponderResponse::register(
     '40001',
     'The class `:class` is undefined.',
     'An error has been occurred in while finding the :entity.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

return ApiResponderResponse::clientError(40001, [
     'class'  => 'Entities/User',
     'entity' => 'user',
],
[
     'field' => [
         'The field has an error.'
     ]
])

返回值将是

{
  "status": 400,
  "developerMessage": "The class `Entities/User` is undefined.",
  "userMessage": "An error has been occurred in while finding the user.",
  "errorCode": "40001",
  "moreInfo": "http://www.example.gov/developer/path/to/help/for/444444",
  "errors": {
      "field": [
          "The field has an error."
      ]
  }
}

省略错误异常

默认情况下，错误存储库在注册先前注册的错误代码或请求不存在的错误代码时抛出异常。但您可以使用以下代码禁用这些异常的抛出。

ApiResponderErrors::disableExceptions();

制作成功响应

根据白宫标准，成功响应必须包含两部分：results和metadata。我们还在元数据中添加了一个名为messages的数组来包含消息。这些部分可以传递给success()方法以生成成功响应。

$results  = [
     [
          'id'    => 1,
          'title' => 'First Item',
     ],
     [
          'id'    => 2,
          'title' => 'Second Item',
     ],
];
$metadata = ['page' => 1];
$messages = [
    'The list of the items may be incomplete in some cases'
];
    
$response = ApiResponderResponse::success($results, $metadata, $messages);

键格式化器

您可以为包生成的所有键注册一个闭包以用于格式化。例如，如果我们有一个将字符串映射到蛇形格式的snake_case()函数，我们可以使用以下代码。

ApiResponderErrors::register(
     '40001',
     'Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here',
     'This is a message that can be passed along to end-users, if needed.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

ApiResponderErrors::registerFormatter(function ($key) {
    return snake_case($key);
});


return ApiResponderErrors::clientError(40001);

此代码的返回结果将是

{
  "status": 400,
  "developer_message": "Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here",
  "user_message": "This is a message that can be passed along to end-users, if needed.",
  "error_code": "40001",
  "more_info": "http://www.example.gov/developer/path/to/help/for/444444"
}

💡 更改键可能会使您的响应不符合白宫标准。

snappmarket / api-responder

维护者

详情