Версія 3.9 додана 2024/05/10 10:10 автором Ashterix
Показати останніх авторів
1 {{box cssClass="floatinginfobox" width="400px" title="**Зміст**"}}
2 {{toc/}}
3 {{/box}}
4
5 Ви можете легко додавати власні API методи до RPC сервера.
6
7 Для цього вам достатньо в будь-якому місці вашого додатку зробити будь-який клас який має стати API Сервісом, цей клас має реалізувати інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService{{/code}}. Цей інтерфейс не навʼязує класу жодної логіки, він необхідний лише для того, щоб Symfony зрозумів, що має його сприймати як сервіс, що доступний для RPC сервера.
8
9 Реалізуйте в вашому класі будь-який публічний метод і він автоматично буде доступний як API Сервіс.
10
11 (% id="cke_bm_318406S" style="display:none" %) (%%)Після виконання попередніх вказівок у вас вже будуть доступні нові методи в API. За замовченням назви методів складаються з {{code language="none"}}<className>.<methodName>{{/code}}.
12
13 = Іменування класів =
14
15 В разі потреби, ви можете створити кілька класів, що будуть доступні як API Сервіси. 
16 Враховуючи їх неймінги ​**<className>.<methodName>**​, рекомендую підходити до вибору назви методу як до простої вказівки що він робить, а до назви класу як до неймспейсу API методу.
17
18 {{success}}
19 == **Гарна практика** ==
20
21 Класс **//Messenger//** містить методи **//sendEmail()//**//,** sendSms()**//,// //класс// **CartResolver** //містить методи **//addProduct()//**//,** getProducts()**//, //**calculateDiscount()**//
22
23 в API будуть доступні методи
24
25 * //**CartResolver.addProduct**//
26 * //**CartResolver.getProducts**//
27 * //**CartResolver.calculateDiscount**//
28 * **//Messenger.sendEmail//**
29 * **//Messenger.sendSms//**
30
31 Навіть просто поглянувши на назви методів зрозуміло що може робити ваш сервер.
32
33 Такий підхід надає можливість використовувати одноіменні методи в різних класах:
34
35 * //**ProductService.create**//
36 * //**ProductService.getName**//
37 * //**UserService.create**//
38 * //**UserService.getName**//
39 {{/success}}
40
41 = Простий старт =
42
43 Наступний приклад має продемонструвати легкість додавання ваших методів до API.
44
45 (% class="row" %)
46 (((
47 (% class="col-xs-12 col-sm-6" %)
48 (((
49 {{code language="php" layout="LINENUMBERS" title="== Код =="}}
50 <?php
51 namespace App\Api\Procedures;
52
53 use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
54
55 class ExampleApi implements IRpcService
56 {
57 public function __construct(
58 // connecting some dependencies to retrieve data
59 ) {}
60
61 public function getUserNameByUuid(
62 string $userId
63 ): string
64 {
65 // some logic get user info by id
66 return 'some result';
67 }
68
69 public function sendEmail(
70 string $email,
71 string $text,
72 string $subject = 'Message without subject'
73 ): bool
74 {
75 // some logic send email
76 return true;
77 }
78 }
79 {{/code}}
80
81 Праворуч приклад документації, що сервер згенерує по цьому класу.
82
83 Основна інформація щодо назв параметрів, їх типів та опціональності отримується завдяки {{code language="none"}}ReflectionClass{{/code}}, важливим є порядок аргументів методу, їх typehint.
84 )))
85
86 (% class="col-xs-12 col-sm-6" %)
87 (((
88 {{code language="json" layout="LINENUMBERS" title="== Документація =="}}
89 {
90 "methods": {
91 "ExampleApi.getUserNameByUuid": {
92 "name": "ExampleApi.getUserNameByUuid",
93 "description": "",
94 "parameters": {
95 "userId": {
96 "type": "string",
97 "name": "userId",
98 "description": "",
99 "optional": false
100 }
101 },
102 "returns": "string",
103 "responseFormat": "string"
104 },
105 "ExampleApi.sendEmail": {
106 "name": "ExampleApi.sendEmail",
107 "description": "",
108 "parameters": {
109 "email": {
110 "type": "string",
111 "name": "email",
112 "description": "",
113 "optional": false
114 },
115 "text": {
116 "type": "string",
117 "name": "text",
118 "description": "",
119 "optional": false
120 },
121 "subject": {
122 "type": "string",
123 "name": "subject",
124 "description": "",
125 "optional": true,
126 "default": "Message without subject"
127 }
128 },
129 "returns": "boolean",
130 "responseFormat": "boolean"
131 }
132 }
133 }
134 {{/code}}
135 )))
136 )))
137
138 Тепер можемо зробити POST запити на обидва нових метода API і подивитися на результат.
139
140 == **POST запити** ==
141
142 (% class="row" %)
143 (((
144 (% class="col-xs-12 col-sm-6" %)
145 (((
146 {{code language="json" layout="LINENUMBERS" title="Request"}}
147 {
148 "id": "example_request",
149 "method": "ExampleApi.getUserNameByUuid",
150 "params": {
151 "userId": "1111"
152 }
153 }
154 {{/code}}
155 )))
156
157 (% class="col-xs-12 col-sm-6" %)
158 (((
159 {{code language="json" layout="LINENUMBERS" title="Response"}}
160 {
161 "id": "example_request",
162 "result": "some result",
163 "jsonrpc": "2.0"
164 }
165 {{/code}}
166
167
168
169 )))
170 )))
171
172 (% class="row" %)
173 (((
174 (% class="col-xs-12 col-sm-6" %)
175 (((
176 {{code language="json" layout="LINENUMBERS" title="Request"}}
177 {
178 "id": "example_request",
179 "method": "ExampleApi.sendEmail",
180 "params": {
181 "email": "user@example.com",
182 "subject": "This is test mail",
183 "text": "Hi! This is test send mail by API"
184 }
185 }
186 {{/code}}
187 )))
188
189 (% class="col-xs-12 col-sm-6" %)
190 (((
191 {{code language="json" layout="LINENUMBERS" title="Response"}}
192 {
193 "id": "example_request",
194 "result": true,
195 "jsonrpc": "2.0"
196 }
197 {{/code}}
198 )))
199 )))
200
201 = Опис методів та параметрів =
202
203 Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.
204
205 Додамо опис методу і параметрів.