Changes for page #[RPC\Response]
Last modified by Ashterix on 2024/05/19 21:13
Summary
-
Page properties (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Content
-
... ... @@ -1,39 +1,33 @@ 1 -{{box cssClass="floatinginfobox"}} 1 +(% class="box floatinginfobox" %) 2 +((( 2 2 == (% style="display:block; margin-top:-30px; text-align:center" %)Summary(%%) == 3 3 4 -(% style="margin-right:auto; width:353px" %) 5 -|(% style="width:141px" %)**Classname**|(% colspan="2" rowspan="1" style="width:79px" %)((( 5 +|**Classname**|(% colspan="2" rowspan="1" %)((( 6 6 Response 7 7 ))) 8 -| (% style="width:141px" %)**Namespace**|(% colspan="2"style="width:79px"%)(((8 +|**Namespace**|(% colspan="2" %)((( 9 9 Ufo\RpcObject\RPC 10 10 ))) 11 -|(% style="width:141px" %)((( 12 -**Target** 13 -)))|(% colspan="2" rowspan="1" style="width:79px" %)method 14 -|(% colspan="3" style="width:141px" %)**Arguments:** 15 -|(% colspan="1" rowspan="3" style="width:141px" %)((( 11 +|**Target**|(% colspan="2" rowspan="1" %)method 12 +|(% colspan="3" %)**Arguments:** 13 +|(% colspan="1" rowspan="3" %)((( 16 16 $responseFormat 17 -)))|(% style="width:79px" %)**type**|(% style="width:153px" %)array 18 -|(% style="width:79px" %)**optional**|(% style="width:153px" %)true 19 -|(% style="width:79px" %)**default**|(% style="width:153px" %)[] 20 -|(% colspan="1" rowspan="3" style="width:141px" %)((( 21 -$dto 22 -)))|(% style="width:79px" %)**type**|(% style="width:153px" %)string 23 -|(% style="width:79px" %)**optional**|(% style="width:153px" %)true 24 -|(% style="width:79px" %)**default**|(% style="width:153px" %)'' 25 -|(% colspan="1" rowspan="3" style="width:141px" %)((( 26 -$collection 27 -)))|(% style="width:79px" %)**type**|(% style="width:153px" %)bool 28 -|(% style="width:79px" %)**optional**|(% style="width:153px" %)true 29 -|(% style="width:79px" %)**default**|(% style="width:153px" %)false 30 -{{/box}} 15 +)))|**type**|array 16 +|**optional**|true 17 +|**default**|[] 18 +|(% colspan="1" rowspan="3" %)$dto|**type**|string 19 +|**optional**|true 20 +|**default**|'' 21 +|(% colspan="1" rowspan="3" %)$collection|**type**|bool 22 +|**optional**|true 23 +|**default**|false 24 +))) 31 31 32 32 = Enhanced Response Format = 33 33 34 -By default, the documentation for the response of each API service is based on the {{codelanguage="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.28 +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. 35 35 36 -To provide clients with more information about the format of more complex responses, the attribute {{codelanguage="none"}}#[RPC\Response]{{/code}}was created.30 +To provide clients with more information about the format of more complex responses, the attribute (% class="box code" %)#[RPC\Response](%%) was created. 37 37 38 38 Let's consider an example that demonstrates the problem and its solution. You have a class containing API methods that return information about users: 39 39 ... ... @@ -41,96 +41,199 @@ 41 41 * getUserInfoAsArray(int $id) - returns information about a user in the form of an array 42 42 * getUsersList() - returns a collection of user objects 43 43 44 -{{code language="php" layout="LINENUMBERS"}} 45 -<?php 46 -namespace App\Api\Procedures; 38 +(% class="box" %) 39 +((( 40 +(% class="code" %) 41 +((( 42 +(% class="linenoswrapper" %) 43 +((( 44 +(% class="linenos" %) 45 +((( 46 +1 47 +2 48 +3 49 +4 50 +5 51 +6 52 +7 53 +8 54 +9 55 +10 56 +11 57 +12 58 +13 59 +14 60 +15 61 +16 62 +17 63 +18 64 +19 65 +20 66 +21 67 +22 68 +23 69 +24 70 +25 71 +26 72 +27 73 +28 74 +29 75 +30 76 +31 77 +32 78 +33\\ 79 +))) 47 47 48 -use App\Services\UserService; 49 -use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService; 50 - 51 -class ExampleApi implements IRpcService 81 +((( 82 +(% style="color: #BC7A00;" %)<?php(%%) 83 +(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures; 84 +\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService; 85 +(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService; 86 +\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService 52 52 { 53 - public function __construct( 54 - protected UserService $userService 88 + (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)( 89 + (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%) 55 55 ) {} 56 - 57 - public function getUserInfo(int $id): User 91 +\\ (% 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 58 58 { 59 - return this->userService->getById($id); 93 + (% 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(%%)); 60 60 } 61 - 62 - public function getUserInfoAsArray(int $id): array 95 +\\ (% 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(%%) 63 63 { 64 - $user = this->getUserInfo($id); 65 - return [ 66 - 'id' => $user->getId(), 67 - 'email' => $user->getEmail(), 68 - 'name' => $user->getName(), 97 + (% 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(%%)); 98 + (% style="font-weight: bold; color: #008000;" %)return(%%) [ 99 + (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(), 100 + (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(), 101 + (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getName(%%)(), 69 69 ]; 70 70 } 71 - 72 - public function getUsersList(): array 104 +\\ (% 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(%%) 73 73 { 74 - return this->userService->getAll(); 106 + (% 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(%%)(); 75 75 } 76 -} 108 +}\\ 109 +))) 110 +))) 111 +))) 112 +))) 77 77 78 -{{/code}} 79 - 80 80 Let's look at the documentation generated by this instruction 81 81 82 -{{code language="json" layout="LINENUMBERS"}} 116 +(% class="box" %) 117 +((( 118 +(% class="code" %) 119 +((( 120 +(% class="linenoswrapper" %) 121 +((( 122 +(% class="linenos" %) 123 +((( 124 +1 125 +2 126 +3 127 +4 128 +5 129 +6 130 +7 131 +8 132 +9 133 +10 134 +11 135 +12 136 +13 137 +14 138 +15 139 +16 140 +17 141 +18 142 +19 143 +20 144 +21 145 +22 146 +23 147 +24 148 +25 149 +26 150 +27 151 +28 152 +29 153 +30 154 +31 155 +32 156 +33 157 +34 158 +35 159 +36 160 +37 161 +38 162 +39 163 +40 164 +41 165 +42 166 +43 167 +44 168 +45 169 +46 170 +47 171 +48 172 +49 173 +50\\ 174 +))) 175 + 176 +((( 83 83 { 84 - "envelope": "JSON-RPC-2.0/UFO-RPC-6", 85 - "contentType": "application/json", 86 - "description": "", 87 - "transport": { 88 - "sync": { 89 - "scheme": "https", 90 - "host": "example.com", 91 - "path": "/api", 92 - "method": "POST" 178 + (% style="font-weight: bold; color: #008000;" %)"envelope"(%%): (% style="color: #BA2121;" %)"JSON-RPC-2.0/UFO-RPC-6"(%%), 179 + (% style="font-weight: bold; color: #008000;" %)"contentType"(%%): (% style="color: #BA2121;" %)"application/json"(%%), 180 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 181 + (% style="font-weight: bold; color: #008000;" %)"transport"(%%): { 182 + (% style="font-weight: bold; color: #008000;" %)"sync"(%%): { 183 + (% style="font-weight: bold; color: #008000;" %)"scheme"(%%): (% style="color: #BA2121;" %)"https"(%%), 184 + (% style="font-weight: bold; color: #008000;" %)"host"(%%): (% style="color: #BA2121;" %)"example.com"(%%), 185 + (% style="font-weight: bold; color: #008000;" %)"path"(%%): (% style="color: #BA2121;" %)"/api"(%%), 186 + (% style="font-weight: bold; color: #008000;" %)"method"(%%): (% style="color: #BA2121;" %)"POST"(%%) 93 93 } 94 94 }, 95 - "methods": { 96 - "ExampleApi.getUserInfo": { 97 - "name": "ExampleApi.getUserInfo", 98 - "description": "", 99 - "parameters": { 100 - "id": { 101 - "type": "integer", 102 - "name": "id", 103 - "description": "", 104 - "optional": false 189 + (% style="font-weight: bold; color: #008000;" %)"methods"(%%): { 190 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): { 191 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%), 192 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 193 + (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): { 194 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): { 195 + (% style="font-weight: bold; color: #008000;" %)"type"(%%): (% style="color: #BA2121;" %)"integer"(%%), 196 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"id"(%%), 197 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 198 + (% style="font-weight: bold; color: #008000;" %)"optional"(%%): (% style="font-weight: bold; color: #008000;" %)false(%%) 105 105 } 106 106 }, 107 - "returns": "object", 108 - "responseFormat": "object" 201 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%), 202 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"object"(%%) 109 109 }, 110 - "ExampleApi.getUserInfoAsArray": { 111 - "name": "ExampleApi.getUserInfoAsArray", 112 - "description": "", 113 - "parameters": { 114 - "id": { 115 - "type": "integer", 116 - "name": "id", 117 - "description": "", 118 - "optional": false 204 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): { 205 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%), 206 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 207 + (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): { 208 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): { 209 + (% style="font-weight: bold; color: #008000;" %)"type"(%%): (% style="color: #BA2121;" %)"integer"(%%), 210 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"id"(%%), 211 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 212 + (% style="font-weight: bold; color: #008000;" %)"optional"(%%): (% style="font-weight: bold; color: #008000;" %)false(%%) 119 119 } 120 120 }, 121 - "returns": "array", 122 - "responseFormat": "array" 215 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 216 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"array"(%%) 123 123 }, 124 - "ExampleApi.getUsersList": { 125 - "name": "ExampleApi.getUsersList", 126 - "description": "", 127 - "parameters": [], 128 - "returns": "array", 129 - "responseFormat": "array" 218 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): { 219 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%), 220 + (% style="font-weight: bold; color: #008000;" %)"description"(%%): (% style="color: #BA2121;" %)""(%%), 221 + (% style="font-weight: bold; color: #008000;" %)"parameters"(%%): [], 222 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 223 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): (% style="color: #BA2121;" %)"array"(%%) 130 130 } 131 131 } 132 132 } 133 -{{/code}} 227 +))) 228 +))) 229 +))) 230 +))) 134 134 135 135 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. 136 136 ... ... @@ -146,98 +146,193 @@ 146 146 ((( 147 147 (% class="col-xs-12 col-sm-6" %) 148 148 ((( 149 -{{code language="php" layout="LINENUMBERS"}} 150 -<?php 151 -namespace App\Api\Procedures; 246 +(% class="box" %) 247 +((( 248 +(% class="code" %) 249 +((( 250 +(% class="linenoswrapper" %) 251 +((( 252 +(% class="linenos" %) 253 +((( 254 +1 255 +2 256 +3 257 +4 258 +5 259 +6 260 +7 261 +8 262 +9 263 +10 264 +11 265 +12 266 +13 267 +14 268 +15 269 +16 270 +17 271 +18 272 +19 273 +20 274 +21 275 +22 276 +23 277 +24 278 +25 279 +26 280 +27 281 +28 282 +29 283 +30 284 +31 285 +32 286 +33 287 +34 288 +35 289 +36 290 +37\\ 291 +))) 152 152 153 -use App\Services\UserService; 154 -use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService; 155 -use Ufo\RpcObject\RPC; 156 - 157 -class ExampleApi implements IRpcService 293 +((( 294 +(% style="color: #BC7A00;" %)<?php(%%) 295 +(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures; 296 +\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService; 297 +(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService; 298 +(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\RpcObject\RPC; 299 +\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService 158 158 { 159 - public function __construct( 160 - protected UserService $userService 301 + (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)( 302 + (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%) 161 161 ) {} 162 - 163 - #[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])] 164 - public function getUserInfo(int $id): User 304 +\\ (% style="font-style: italic; color: #408080;" %)#[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])] 305 +(%%) (% 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 165 165 { 166 - return this->userService->getById($id); 307 + (% 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(%%)); 167 167 } 168 - 169 - #[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])] 170 - public function getUserInfoAsArray(int $id): array 309 +\\ (% style="font-style: italic; color: #408080;" %)#[RPC\Response(['id' => 'int', 'email' => 'string', 'name' => 'string'])] 310 +(%%) (% 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(%%) 171 171 { 172 - $user = this->getUserInfo($id); 173 - return [ 174 - 'id' => $user->getId(), 175 - 'email' => $user->getEmail(), 176 - 'name' => $user's->getName(), 312 + (% 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(%%)); 313 + (% style="font-weight: bold; color: #008000;" %)return(%%) [ 314 + (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(), 315 + (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(), 316 + (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #BA2121;" %)'s->getName(), 177 177 ]; 178 178 } 179 - 180 - #[RPC\Response([['id' => 'int', 'email' => 'string', 'name' => 'string'])]] 181 - public function getUsersList(): array 319 +\\ #[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;" %)'(%%)])]] 320 + (% 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(%%) 182 182 { 183 - return this->userService->getAll(); 322 + (% 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(%%)(); 184 184 } 185 -} 324 +}\\ 325 +))) 326 +))) 327 +))) 328 +))) 186 186 187 -{{/code}} 188 - 189 189 Note the changed documentation format on the right, responseFormat now has detail and provides a clear idea of the response structure. 190 190 ))) 191 191 192 192 (% class="col-xs-12 col-sm-6" %) 193 193 ((( 194 - {{code language="json" layout="LINENUMBERS" title="(% class=~"boxwarningmessage~" %)335 +(% class="box" %) 195 195 ((( 337 +(% class="box warningmessage" %) 338 +((( 196 196 To simplify the documentation, in the response example I will remove other elements except those intended to demonstrate 197 -)))"}} 340 +))) 341 + 342 +(% class="code" %) 343 +((( 344 +(% class="linenoswrapper" %) 345 +((( 346 +(% class="linenos" %) 347 +((( 348 +1 349 +2 350 +3 351 +4 352 +5 353 +6 354 +7 355 +8 356 +9 357 +10 358 +11 359 +12 360 +13 361 +14 362 +15 363 +16 364 +17 365 +18 366 +19 367 +20 368 +21 369 +22 370 +23 371 +24 372 +25 373 +26 374 +27 375 +28 376 +29 377 +30 378 +31 379 +32 380 +33 381 +34 382 +35 383 +36\\ 384 +))) 385 + 386 +((( 198 198 { 199 - "methods": { 200 - "ExampleApi.getUserInfo": { 201 - "name": "ExampleApi.getUserInfo", 202 - ..., 203 - "returns": "object", 204 - "responseFormat": { 205 - "id": "int", 206 - "email": "string", 207 - "name": "string" 388 + (% style="font-weight: bold; color: #008000;" %)"methods"(%%): { 389 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): { 390 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%), 391 + (% style="border: 1px solid #FF0000;" %)...,(%%) 392 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%), 393 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): { 394 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 395 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 396 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 208 208 } 209 209 }, 210 - "ExampleApi.getUserInfoAsArray": { 211 - "name": "ExampleApi.getUserInfoAsArray", 212 - ..., 213 - "returns": "array", 214 - "responseFormat": { 215 - "id": "int", 216 - "email": "string", 217 - "name": "string" 399 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): { 400 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%), 401 + (% style="border: 1px solid #FF0000;" %)...,(%%) 402 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 403 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): { 404 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 405 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 406 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 218 218 } 219 219 }, 220 - "ExampleApi.getUsersList": { 221 - "name": "ExampleApi.getUsersList", 222 - ..., 223 - "returns": "array", 224 - "responseFormat": [ 409 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): { 410 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%), 411 + (% style="border: 1px solid #FF0000;" %)...,(%%) 412 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 413 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): [ 225 225 { 226 - "id": "int", 227 - "email": "string", 228 - "name": "string" 415 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 416 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 417 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 229 229 } 230 230 ] 231 231 } 232 232 } 233 233 } 234 -{{/code}} 423 +))) 424 +))) 425 +))) 426 +))) 235 235 236 236 237 237 ))) 238 238 ))) 239 239 240 -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. 432 +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. 241 241 242 242 == **Option 2 - (recommended)** == 243 243 ... ... @@ -248,103 +248,220 @@ 248 248 ((( 249 249 (% class="col-xs-12 col-sm-6" %) 250 250 ((( 251 -{{code language="php" layout="LINENUMBERS"}} 252 -<?php 253 -namespace App\Api\DTO; 443 +(% class="box" %) 444 +((( 445 +(% class="code" %) 446 +((( 447 +(% class="linenoswrapper" %) 448 +((( 449 +(% class="linenos" %) 450 +((( 451 +1 452 +2 453 +3 454 +4 455 +5 456 +6 457 +7 458 +8 459 +9\\ 460 +))) 254 254 255 -readonly class UserDTO 462 +((( 463 +(% style="color: #BC7A00;" %)<?php(%%) 464 +(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\DTO; 465 +\\readonly (% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)UserDTO(%%) 256 256 { 257 - public int $id; 258 - public string $email; 259 - public string $name; 467 + (% style="font-weight: bold; color: #008000;" %)public(%%) int (% style="color: #19177C;" %)$id(%%); 468 + (% style="font-weight: bold; color: #008000;" %)public(%%) string (% style="color: #19177C;" %)$email(%%); 469 + (% style="font-weight: bold; color: #008000;" %)public(%%) string (% style="color: #19177C;" %)$name(%%); 260 260 } 261 -{{/code}} 471 +))) 472 +))) 473 +))) 474 +))) 262 262 263 -{{code language="php" layout="LINENUMBERS"}} 264 -<?php 265 -namespace App\Api\Procedures; 476 +(% class="box" %) 477 +((( 478 +(% class="code" %) 479 +((( 480 +(% class="linenoswrapper" %) 481 +((( 482 +(% class="linenos" %) 483 +((( 484 +1 485 +2 486 +3 487 +4 488 +5 489 +6 490 +7 491 +8 492 +9 493 +10 494 +11 495 +12 496 +13 497 +14 498 +15 499 +16 500 +17 501 +18 502 +19 503 +20 504 +21 505 +22 506 +23 507 +24 508 +25 509 +26 510 +27 511 +28 512 +29 513 +30 514 +31 515 +32 516 +33 517 +34 518 +35 519 +36 520 +37 521 +38\\ 522 +))) 266 266 267 -use App\Services\UserService; 268 -use Ufo\JsonRpcBundle.ApiMethod\Interfaces\IRpcService; 269 -use Ufo\RpcObject\RPC; 270 -use App\Api\DTO\UserDTO; 271 - 272 -class ExampleApi implements IRpcService 524 +((( 525 +(% style="color: #BC7A00;" %)<?php(%%) 526 +(% style="font-weight: bold; color: #008000;" %)namespace(%%) App\Api\Procedures; 527 +\\(% style="font-weight: bold; color: #008000;" %)use(%%) App\Services\UserService; 528 +(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\JsonRpcBundle(% style="color: #666666;" %).(%%)ApiMethod\Interfaces\IRpcService; 529 +(% style="font-weight: bold; color: #008000;" %)use(%%) Ufo\RpcObject\RPC; 530 +(% style="font-weight: bold; color: #008000;" %)use(%%) App\Api\DTO\UserDTO; 531 +\\(% style="font-weight: bold; color: #008000;" %)class(%%) (% style="font-weight: bold; color: #0000FF;" %)ExampleApi(%%) (% style="font-weight: bold; color: #008000;" %)implements(%%) IRpcService 273 273 { 274 - public function __construct( 275 - protected UserService $userService 533 + (% style="font-weight: bold; color: #008000;" %)public(%%) (% style="font-weight: bold; color: #008000;" %)function(%%) (% style="color: #0000FF;" %)~_~_construct(%%)( 534 + (% style="font-weight: bold; color: #008000;" %)protected(%%) UserService (% style="color: #19177C;" %)$userService(%%) 276 276 ) {} 277 - 278 - #[RPC\Response(dto: UserDTO::class)] 279 - public function getUserInfo(int $id): User 536 +\\ (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class)] 537 +(%%) (% 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 280 280 { 281 - return this->userService->getById($id); 539 + (% 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(%%)); 282 282 } 283 - 284 - #[RPC\Response(dto: UserDTO::class)] 285 - public function getUserInfoAsArray(int $id): array 541 +\\ (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class)] 542 +(%%) (% 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(%%) 286 286 { 287 - $user = this->getUserInfo($id); 288 - return [ 289 - 'id' => $user->getId(), 290 - 'email' => $user->getEmail(), 291 - 'name' => $user's->getName(), 544 + (% 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(%%)); 545 + (% style="font-weight: bold; color: #008000;" %)return(%%) [ 546 + (% style="color: #BA2121;" %)'id'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getId(%%)(), 547 + (% style="color: #BA2121;" %)'email'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getEmail(%%)(), 548 + (% style="color: #BA2121;" %)'name'(%%) (% style="color: #666666;" %)=>(%%) (% style="color: #19177C;" %)$user(% style="border: 1px solid #FF0000;" %)'(%%)s(% style="color: #666666;" %)->(% style="color: #7D9029;" %)getName(%%)(), 292 292 ]; 293 293 } 294 - 295 - #[RPC\Response(dto: UserDTO::class, collection: true)] 296 - public function getUsersList(): array 551 +\\ (% style="font-style: italic; color: #408080;" %)#[RPC\Response(dto: UserDTO::class, collection: true)] 552 +(%%) (% 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(%%) 297 297 { 298 - return this->userService->getAll(); 554 + (% 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(%%)(); 299 299 } 300 -} 301 - 302 -{{/code}} 556 +}\\ 303 303 ))) 558 +))) 559 +))) 560 +))) 561 +))) 304 304 305 305 (% class="col-xs-12 col-sm-6" %) 306 306 ((( 307 - {{code language="json" layout="LINENUMBERS" title="(% class=~"boxwarningmessage~" %)565 +(% class="box" %) 308 308 ((( 567 +(% class="box warningmessage" %) 568 +((( 309 309 To simplify the documentation, in the response example I will remove other elements except those intended to demonstrate 310 -)))"}} 570 +))) 571 + 572 +(% class="code" %) 573 +((( 574 +(% class="linenoswrapper" %) 575 +((( 576 +(% class="linenos" %) 577 +((( 578 +1 579 +2 580 +3 581 +4 582 +5 583 +6 584 +7 585 +8 586 +9 587 +10 588 +11 589 +12 590 +13 591 +14 592 +15 593 +16 594 +17 595 +18 596 +19 597 +20 598 +21 599 +22 600 +23 601 +24 602 +25 603 +26 604 +27 605 +28 606 +29 607 +30 608 +31 609 +32 610 +33 611 +34 612 +35 613 +36\\ 614 +))) 615 + 616 +((( 311 311 { 312 - "methods": { 313 - "ExampleApi.getUserInfo": { 314 - "name": "ExampleApi.getUserInfo", 315 - ..., 316 - "returns": "object", 317 - "responseFormat": { 318 - "id": "int", 319 - "email": "string", 320 - "name": "string" 618 + (% style="font-weight: bold; color: #008000;" %)"methods"(%%): { 619 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfo"(%%): { 620 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfo"(%%), 621 + (% style="border: 1px solid #FF0000;" %)...,(%%) 622 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"object"(%%), 623 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): { 624 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 625 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 626 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 321 321 } 322 322 }, 323 - "ExampleApi.getUserInfoAsArray": { 324 - "name": "ExampleApi.getUserInfoAsArray", 325 - ..., 326 - "returns": "array", 327 - "responseFormat": { 328 - "id": "int", 329 - "email": "string", 330 - "name": "string" 629 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUserInfoAsArray"(%%): { 630 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUserInfoAsArray"(%%), 631 + (% style="border: 1px solid #FF0000;" %)...,(%%) 632 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 633 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): { 634 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 635 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 636 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 331 331 } 332 332 }, 333 - "ExampleApi.getUsersList": { 334 - "name": "ExampleApi.getUsersList", 335 - ..., 336 - "returns": "array", 337 - "responseFormat": [ 639 + (% style="font-weight: bold; color: #008000;" %)"ExampleApi.getUsersList"(%%): { 640 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"ExampleApi.getUsersList"(%%), 641 + (% style="border: 1px solid #FF0000;" %)...,(%%) 642 + (% style="font-weight: bold; color: #008000;" %)"returns"(%%): (% style="color: #BA2121;" %)"array"(%%), 643 + (% style="font-weight: bold; color: #008000;" %)"responseFormat"(%%): [ 338 338 { 339 - "id": "int", 340 - "email": "string", 341 - "name": "string" 645 + (% style="font-weight: bold; color: #008000;" %)"id"(%%): (% style="color: #BA2121;" %)"int"(%%), 646 + (% style="font-weight: bold; color: #008000;" %)"email"(%%): (% style="color: #BA2121;" %)"string"(%%), 647 + (% style="font-weight: bold; color: #008000;" %)"name"(%%): (% style="color: #BA2121;" %)"string"(%%) 342 342 } 343 343 ] 344 344 } 345 345 } 346 346 } 347 -{{/code}} 653 +))) 654 +))) 655 +))) 656 +))) 348 348 349 349 (% class="box successmessage" %) 350 350 (((