Changes for page #[RPC\Response]

Last modified by Ashterix on 2024/05/19 21:13

From version 1.1

edited by Ashterix
on 2024/05/10 14:41

Change comment: There is no comment for this version

To version 5.1

edited by Ashterix
on 2024/05/19 21:13

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,39 +1,33 @@
--{{box cssClass="floatinginfobox" width="400px"}}
++(% class="box floatinginfobox" %)
++(((
  == (% style="display:block; margin-top:-30px; text-align:center" %)Summary(%%) ==
--(% style="margin-right:auto; width:353px" %)
--|(% style="width:141px" %)**Classname**|(% colspan="2" rowspan="1" style="width:79px" %)(((
++|**Classname**|(% colspan="2" rowspan="1" %)(((
  Response
  )))
--|(% style="width:141px" %)**Namespace**|(% colspan="2" style="width:79px" %)(((
++|**Namespace**|(% colspan="2" %)(((
  Ufo\RpcObject\RPC
  )))
--|(% style="width:141px" %)(((
--**Target**
--)))|(% colspan="2" rowspan="1" style="width:79px" %)method
--|(% colspan="3" style="width:141px" %)**Arguments:**
--|(% colspan="1" rowspan="3" style="width:141px" %)(((
++|**Target**|(% colspan="2" rowspan="1" %)method
++|(% colspan="3" %)**Arguments:**
++|(% colspan="1" rowspan="3" %)(((
  $responseFormat
--)))|(% style="width:79px" %)**type**|(% style="width:153px" %)array
--|(% style="width:79px" %)**optional**|(% style="width:153px" %)true
--|(% style="width:79px" %)**default**|(% style="width:153px" %)[]
--|(% colspan="1" rowspan="3" style="width:141px" %)(((
--$dto
--)))|(% style="width:79px" %)**type**|(% style="width:153px" %)string
--|(% style="width:79px" %)**optional**|(% style="width:153px" %)true
--|(% style="width:79px" %)**default**|(% style="width:153px" %)''
--|(% colspan="1" rowspan="3" style="width:141px" %)(((
--$collection
--)))|(% style="width:79px" %)**type**|(% style="width:153px" %)bool
--|(% style="width:79px" %)**optional**|(% style="width:153px" %)true
--|(% style="width:79px" %)**default**|(% style="width:153px" %)false
--{{/box}}
++)))|**type**|array
++|**optional**|true
++|**default**|[]
++|(% colspan="1" rowspan="3" %)$dto|**type**|string
++|**optional**|true
++|**default**|''
++|(% colspan="1" rowspan="3" %)$collection|**type**|bool
++|**optional**|true
++|**default**|false
++)))
  = Enhanced Response Format =
--By default, the documentation for the response of each API service is based on the {{code language="none"}}return type{{/code}}, which works well with primitive types. However, if your method returns an associative array, an object, or a collection of objects, the information about the data type of the response becomes insufficient.
++By default, the documentation for the response of each API service is based on the (% class="box code" %)return type(%%), which works well with primitive types. However, if your method returns an associative array, an object, or a collection of objects, the information about the data type of the response becomes insufficient.
--To provide clients with more information about the format of more complex responses, the attribute {{code language="none"}}#[RPC\Response]{{/code}} was created.
++To provide clients with more information about the format of more complex responses, the attribute (% class="box code" %)#[RPC\Response](%%) was created.
  Let's consider an example that demonstrates the problem and its solution. You have a class containing API methods that return information about users:
@@ -41,90 +41,199 @@
  * getUserInfoAsArray(int $id) - returns information about a user in the form of an array
  * getUsersList() - returns a collection of user objects
--{{code language="php" layout="LINENUMBERS"}}
--<?php
--namespace App\Api\Procedures;
++(% class="box" %)
++(((
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33\\
++)))
--use App\Services\UserService;
--use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
--
--class ExampleApi implements IRpcService
++(((
++(% style="color: #BC7A00;" %)<?php(%%)
++(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures;
++\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService;
++(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
++\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService
  {
--    public function __construct(
--        protected UserService $userService
++    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)(
++        (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%)
      ) {}
--
--    public function getUserInfo(int $id): User
++\\    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfo(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) User
      {
--        return this->userService->getById($id);
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getById(%%)((% style="color: #19177C;" %)$id(%%));
      }
--
--    public function getUserInfoAsArray(int $id): array
++\\    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfoAsArray(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        $user = this->getUserInfo($id);
--        return [
--            'id' => $user->getId(),
--            'email' => $user->getEmail(),
--            'name' => $user->getName(),
++        (% style="color: #19177C;" %)$user(%%) (% style="color: #666666;" %)=(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getUserInfo(%%)((% style="color: #19177C;" %)$id(%%));
++        (% style="font-weight: bold; color: #008000;" %)return(%%) [
++            (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(),
++            (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(),
++            (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getName(%%)(),
          ];
      }
--
--    public function getUsersList(): array
++\\    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUsersList(%%)()(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        return this->userService->getAll();
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getAll(%%)();
      }
--}
++}\\
++)))
++)))
++)))
++)))
--{{/code}}
--
  Let's look at the documentation generated by this instruction
--{{code language="json" layout="LINENUMBERS"}}
++(% class="box" %)
++(((
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33
++34
++35
++36
++37
++38
++39
++40
++41
++42
++43
++44
++45
++46
++47
++48
++49
++50\\
++)))
++
++(((
  {
--    "envelope": "JSON-RPC-2.0/UFO-RPC-6",
--    "transport": "POST",
--    "target": "/api",
--    "contentType": "application/json",
--    "description": "",
--    "methods": {
--        "ExampleApi.getUserInfo": {
--            "name": "ExampleApi.getUserInfo",
--            "description": "",
--            "parameters": {
--                "id": {
--                    "type": "integer",
--                    "name": "id",
--                    "description": "",
--                    "optional": false
++    (% style="font-weight: bold; color: #008000;" %)"envelope"(%%): (% style="color: #BA2121;" %)"JSON-RPC-2.0/UFO-RPC-6"(%%),
++    (% style="font-weight: bold; color: #008000;" %)"contentType"(%%): (% style="color: #BA2121;" %)"application/json"(%%),
++    (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++    (% style="font-weight: bold; color: #008000;" %)"transport"(%%): {
++        (% style="font-weight: bold; color: #008000;" %)"sync"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"scheme"(%%): (% style="color: #BA2121;" %)"https"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"host"(%%): (% style="color: #BA2121;" %)"example.com"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"path"(%%): (% style="color: #BA2121;" %)"/api"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"method"(%%): (% style="color: #BA2121;" %)"POST"(%%)
++        }
++    },
++    (% style="font-weight: bold; color: #008000;" %)"methods"(%%): {
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++            (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): {
++                    (% style="font-weight: bold; color: #008000;" %)"type"(%%): (% style="color: #BA2121;" %)"integer"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"id"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"optional"(%%): (% style="font-weight: bold; color: #008000;" %)false(%%)
                  }
              },
--            "returns": "object",
--            "responseFormat": "object"
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"object"(%%)
          },
--        "ExampleApi.getUserInfoAsArray": {
--            "name": "ExampleApi.getUserInfoAsArray",
--            "description": "",
--            "parameters": {
--                "id": {
--                    "type": "integer",
--                    "name": "id",
--                    "description": "",
--                    "optional": false
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++            (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): {
++                    (% style="font-weight: bold; color: #008000;" %)"type"(%%): (% style="color: #BA2121;" %)"integer"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"id"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"optional"(%%): (% style="font-weight: bold; color: #008000;" %)false(%%)
                  }
              },
--            "returns": "array",
--            "responseFormat": "array"
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"array"(%%)
          },
--        "ExampleApi.getUsersList": {
--            "name": "ExampleApi.getUsersList",
--            "description": "",
--            "parameters": [],
--            "returns": "array",
--            "responseFormat": "array"
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%),
++            (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): [],
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"array"(%%)
          }
      }
  }
--{{/code}}
++)))
++)))
++)))
++)))
  We are interested in returns and responseFormat (lines 19-20, 33-34, and 40-41), we see that the RPC Server interpreted User as an object and this information does not tell the client how to work with the response object, what properties it should have, nor is there information about the responses of the other two methods, in both cases an array should be returned and we know nothing about its contents.
@@ -140,98 +140,193 @@
  (((
  (% class="col-xs-12 col-sm-6" %)
  (((
--{{code language="php" layout="LINENUMBERS"}}
--<?php
--namespace App\Api\Procedures;
++(% class="box" %)
++(((
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33
++34
++35
++36
++37\\
++)))
--use App\Services\UserService;
--use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
--use Ufo\RpcObject\RPC;
--
--class ExampleApi implements IRpcService
++(((
++(% style="color: #BC7A00;" %)<?php(%%)
++(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures;
++\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService;
++(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
++(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\RpcObject\RPC;
++\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService
  {
--    public function __construct(
--        protected UserService $userService
++    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)(
++        (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%)
      ) {}
--
--    #[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])]
--    public function getUserInfo(int $id): User
++\\    (% style="font-style: italic; color: #408080;" %)#[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])]
++(%%)    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfo(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) User
      {
--        return this->userService->getById($id);
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getById(%%)((% style="color: #19177C;" %)$id(%%));
      }
--
--    #[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])]
--    public function getUserInfoAsArray(int $id): array
++\\    (% style="font-style: italic; color: #408080;" %)#[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])]
++(%%)    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfoAsArray(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        $user = this->getUserInfo($id);
--        return [
--            'id' => $user->getId(),
--            'email' => $user->getEmail(),
--            'name' => $user's->getName(),
++        (% style="color: #19177C;" %)$user(%%) (% style="color: #666666;" %)=(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getUserInfo(%%)((% style="color: #19177C;" %)$id(%%));
++        (% style="font-weight: bold; color: #008000;" %)return(%%) [
++            (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(),
++            (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(),
++            (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #BA2121;" %)'s->getName(),
          ];
      }
--
--    #[RPC\Response([['id' => 'int', 'email' => 'string', 'name' => 'string'])]]
--    public function getUsersList(): array
++\\    #[RPC\Response(~[~['(%%)id(% style="color: #BA2121;" %)' => '(%%)int(% style="color: #BA2121;" %)', '(%%)email(% style="color: #BA2121;" %)' => '(%%)string(% style="color: #BA2121;" %)', '(%%)name(% style="color: #BA2121;" %)' => '(%%)string(% style="border: 1px solid #FF0000;" %)'(%%)])]]
++    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUsersList(%%)()(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        return this->userService->getAll();
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getAll(%%)();
      }
--}
++}\\
++)))
++)))
++)))
++)))
--{{/code}}
--
  Note the changed documentation format on the right, responseFormat now has detail and provides a clear idea of the response structure.
  )))
  (% class="col-xs-12 col-sm-6" %)
  (((
--{{code language="json" layout="LINENUMBERS" title="(% class=~"box warningmessage~" %)
++(% class="box" %)
  (((
++(% class="box warningmessage" %)
++(((
  To simplify the documentation, in the response example I will remove other elements except those intended to demonstrate
--)))"}}
++)))
++
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33
++34
++35
++36\\
++)))
++
++(((
  {
--    "methods": {
--        "ExampleApi.getUserInfo": {
--            "name": "ExampleApi.getUserInfo",
--            ...
--            "returns": "object",
--            "responseFormat": {
--                "id": "int",
--                "email": "string",
--                "name": "string"
++    (% style="font-weight: bold; color: #008000;" %)"methods"(%%): {
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
              }
          },
--        "ExampleApi.getUserInfoAsArray": {
--            "name": "ExampleApi.getUserInfoAsArray",
--            ...
--            "returns": "array",
--            "responseFormat": {
--                "id": "int",
--                "email": "string",
--                "name": "string"
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
              }
          },
--        "ExampleApi.getUsersList": {
--            "name": "ExampleApi.getUsersList",
--            ...
--            "returns": "array",
--            "responseFormat": [
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): [
                  {
--                    "id": "int",
--                    "email": "string",
--                    "name": "string"
++                    (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
                  }
              ]
          }
      }
  }
--{{/code}}
++)))
++)))
++)))
++)))
  )))
  )))
--You might notice that using an array in such an example seems inconvenient because even within just this one class we used it three times and if you need to change the structure of the user properties this array will have to be changed in many places. In other words, this violates [[DRY>>https://ru.wikipedia.org/wiki/Don%E2%80%99t_repeat_yourself]]. That's why I mentioned that this option is only suitable as a one-time. In other cases, you need to use a different approach.
++You might notice that using an array in such an example seems inconvenient because even within just this one class we used it three times and if you need to change the structure of the user properties this array will have to be changed in many places. In other words, this violates [[DRY>>url:https://ru.wikipedia.org/wiki/Don%E2%80%99t_repeat_yourself]]. That's why I mentioned that this option is only suitable as a one-time. In other cases, you need to use a different approach.
  == **Option 2 - (recommended)** ==
@@ -242,103 +242,220 @@
  (((
  (% class="col-xs-12 col-sm-6" %)
  (((
--{{code language="php" layout="LINENUMBERS"}}
--<?php
--namespace App\Api\DTO;
++(% class="box" %)
++(((
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9\\
++)))
--readonly class UserDTO
++(((
++(% style="color: #BC7A00;" %)<?php(%%)
++(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\DTO;
++\\readonly (% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)UserDTO(%%)
  {
--    public int $id;
--    public string $email;
--    public string $name;
++    (% style="font-weight: bold; color: #008000;" %)public(%%) int (% style="color: #19177C;" %)$id(%%);
++    (% style="font-weight: bold; color: #008000;" %)public(%%) string (% style="color: #19177C;" %)$email(%%);
++    (% style="font-weight: bold; color: #008000;" %)public(%%) string (% style="color: #19177C;" %)$name(%%);
  }
--{{/code}}
++)))
++)))
++)))
++)))
--{{code language="php" layout="LINENUMBERS"}}
--<?php
--namespace App\Api\Procedures;
++(% class="box" %)
++(((
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33
++34
++35
++36
++37
++38\\
++)))
--use App\Services\UserService;
--use Ufo\JsonRpcBundle.ApiMethod\Interfaces\IRpcService;
--use Ufo\RpcObject\RPC;
--use App\Api\DTO\UserDTO;
--
--class ExampleApi implements IRpcService
++(((
++(% style="color: #BC7A00;" %)<?php(%%)
++(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures;
++\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService;
++(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle(% style="color: #666666;" %).(%%)ApiMethod\Interfaces\IRpcService;
++(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\RpcObject\RPC;
++(% style="font-weight: bold; color: #008000;" %)use(%%) App\Api\DTO\UserDTO;
++\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService
  {
--    public function __construct(
--        protected UserService $userService
++    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)(
++        (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%)
      ) {}
--
--    #[RPC\Response(dto: UserDTO::class)]
--    public function getUserInfo(int $id): User
++\\    (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class)]
++(%%)    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfo(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) User
      {
--        return this->userService->getById($id);
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getById(%%)((% style="color: #19177C;" %)$id(%%));
      }
--
--    #[RPC\Response(dto: UserDTO::class)]
--    public function getUserInfoAsArray(int $id): array
++\\    (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class)]
++(%%)    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUserInfoAsArray(%%)(int (% style="color: #19177C;" %)$id(%%))(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        $user = this->getUserInfo($id);
--        return [
--            'id' => $user->getId(),
--            'email' => $user->getEmail(),
--            'name' => $user's->getName(),
++        (% style="color: #19177C;" %)$user(%%) (% style="color: #666666;" %)=(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getUserInfo(%%)((% style="color: #19177C;" %)$id(%%));
++        (% style="font-weight: bold; color: #008000;" %)return(%%) [
++            (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(),
++            (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(),
++            (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="border: 1px solid #FF0000;" %)'(%%)s(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getName(%%)(),
          ];
      }
--
--    #[RPC\Response(dto: UserDTO::class, collection: true)]
--    public function getUsersList(): array
++\\    (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class, collection: true)]
++(%%)    (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)getUsersList(%%)()(% style="color: #666666;" %):(%%) (% style="font-weight: bold; color: #008000;" %)array(%%)
      {
--        return this->userService->getAll();
++        (% style="font-weight: bold; color: #008000;" %)return(%%) (% style="font-weight: bold; color: #008000;" %)this(% style="color: #666666;" %)->(% style="color: #7D9029;" %)userService(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getAll(%%)();
      }
--}
--
--{{/code}}
++}\\
  )))
++)))
++)))
++)))
++)))
  (% class="col-xs-12 col-sm-6" %)
  (((
--{{code language="json" layout="LINENUMBERS" title="(% class=~"box warningmessage~" %)
++(% class="box" %)
  (((
++(% class="box warningmessage" %)
++(((
  To simplify the documentation, in the response example I will remove other elements except those intended to demonstrate
--)))"}}
++)))
++
++(% class="code" %)
++(((
++(% class="linenoswrapper" %)
++(((
++(% class="linenos" %)
++(((
++1
++2
++3
++4
++5
++6
++7
++8
++9
++10
++11
++12
++13
++14
++15
++16
++17
++18
++19
++20
++21
++22
++23
++24
++25
++26
++27
++28
++29
++30
++31
++32
++33
++34
++35
++36\\
++)))
++
++(((
  {
--    "methods": {
--        "ExampleApi.getUserInfo": {
--            "name": "ExampleApi.getUserInfo",
--            ...
--            "returns": "object",
--            "responseFormat": {
--                "id": "int",
--                "email": "string",
--                "name": "string"
++    (% style="font-weight: bold; color: #008000;" %)"methods"(%%): {
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
              }
          },
--        "ExampleApi.getUserInfoAsArray": {
--            "name": "ExampleApi.getUserInfoAsArray",
--
--            "returns": "array",
--            "responseFormat": {
--                "id": "int",
--                "email": "string",
--                "name": "string"
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): {
++                (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
              }
          },
--        "ExampleApi.getUsersList": {
--            "name": "ExampleApi.getUsersList",
--
--            "returns": "array",
--            "responseFormat": [
++        (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): {
++            (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%),
++            (% style="border: 1px solid #FF0000;" %)...,(%%)
++            (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%),
++            (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): [
                  {
--                    "id": "int",
--                    "email": "string",
--                    "name": "string"
++                    (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%),
++                    (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%)
                  }
              ]
          }
      }
  }
--{{/code}}
++)))
++)))
++)))
++)))
  (% class="box successmessage" %)
  (((
@@ -346,4 +346,3 @@
  )))
  )))
  )))
--

Changes for page #[RPC\Response]

Summary

Details

Navigation

Child Pages