Зміни в документі 2. Налаштування бандла

Остання зміна 2024/07/11 11:49 автором Ashterix
Від версії 3.1
редаговано Ashterix
дата 2024/07/11 11:40
Змінити коментар: Немає коментарів для цієї версії
До версії 2.2
редаговано Ashterix
дата 2024/07/11 10:05
Змінити коментар: Немає коментарів для цієї версії

Підсумок

Подробиці

Властивості сторінки
Вміст
... ... @@ -16,28 +16,37 @@
16 16  
17 17  Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
18 18  
19 -== Параметри {{code language="none"}}protected_api{{/code}} та {{code language="none"}}protected_doc{{/code}} (boolean) ==
19 +== Параметр {{code language="none"}}protected_methods{{/code}} ==
20 20  
21 21  (% class="wikigeneratedid" %)
22 -Ці параметри вказує чи мають бути захищені API методи та документація, відповідно.
22 +Цей параметр приймає масив назв http методів, які мають бути захищені.
23 23  
24 24  (% class="wikigeneratedid" %)
25 -За замовченням апі методи захищені, а документація відкрита.
25 +За замовченням ввімкнут захист лише для методу POST. Ви можете:
26 26  
27 +* вказати пустий масив {{code language="none"}}[]{{/code}} щоб зробити API повністю відкритим
28 +
27 27  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
28 28  ufo_json_rpc:
29 29   security:
30 - protected_api: true # Protection API requests
31 - protected_doc: false # Protection API documentation
32 + protected_methods: []
32 32  {{/code}}
33 33  
34 -(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_api{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
35 +* вказати додатково захист для методу GET, що зробить запит документації недоступним без токену в заголовках запиту
35 35  
37 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
38 +ufo_json_rpc:
39 + security:
40 + protected_methods: ['GET', 'POST']
41 +{{/code}}
42 +
43 +(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_methods{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
44 +
36 36  Перш за все, треба визначитися з назвою токену.
37 37  
38 -== Параметр {{code language="none"}}token_name{{/code}} ==
47 +== Параметр {{code language="none"}}token_key_in_header{{/code}} ==
39 39  
40 -Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_name: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
49 +Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_key_in_header: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
41 41  
42 42  {{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
43 43  Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
... ... @@ -57,16 +57,8 @@
57 57  
58 58  
59 59  
69 +== Параметр {{code language="none"}}clients_tokens{{/code}} ==
60 60  
61 -
62 -
63 -
64 -
65 -
66 -
67 -
68 -Параметр {{code language="none"}}clients_tokens{{/code}}
69 -
70 70  Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
71 71  
72 72  Тут є певна варіативність.
... ... @@ -86,7 +86,8 @@
86 86  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
87 87  ufo_json_rpc:
88 88   security:
89 - token_name: 'Ufo-RPC-Token'
90 + protected_methods: ['GET', 'POST']
91 + token_key_in_header: 'Ufo-RPC-Token'
90 90   clients_tokens:
91 91   - 'ClientTokenExample' # hardcoded token example. Importantly!!! Replace or delete it!
92 92  
... ... @@ -107,6 +107,7 @@
107 107  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
108 108  ufo_json_rpc:
109 109   security:
112 + protected_methods: ['GET', 'POST']
110 110   token_key_in_header: 'Ufo-RPC-Token'
111 111   clients_tokens:
112 112   - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
... ... @@ -189,32 +189,45 @@
189 189  
190 190  = Блок {{code language="none"}}docs{{/code}} =
191 191  
192 -Цей блок налаштовує деякі параметри генерації документації коли ви робите GET запит на RPC Server.
195 +Це блок який налаштовує генерацію документації коли ви робите GET запит на RPC Server
193 193  
194 -(% class="box infomessage" %)
195 -(((
196 -Починаючи з версії 7, JsonRpcBundle генерує API документацію, що відповідає специфікації [[OpenRpc>>https://spec.open-rpc.org/]]
197 -)))
197 +== Секція {{code language="none"}}response{{/code}} ==
198 198  
199 -* {{code language="none"}}project_name{{/code}}: Назва проєкту, що буде відображена в документації
200 -* {{code language="none"}}project_description{{/code}}: Опис проєкту
201 -* {{code language="none"}}project_version{{/code}}: Поточна версія вашого API
202 -* {{code language="none"}}async_dsn_info{{/code}}: Відповідає за відображення в документації інформації про асинхронний транспорт
203 -* (% id="cke_bm_826282S" style="display:none" %) {{code language="none"}}validations.symfony_asserts{{/code}}(%%): <bool> Відповідає за відображення рядку очікувань валідації для параметра (якщо ви використовуєте [[валідацію>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]])
199 +Містить налаштування, що відповідають за вміст відповіді.
204 204  
201 +=== Параметр {{code language="none"}}key_for_methods{{/code}} ===
202 +
203 +Цей параметр дозволяє вказати назву ключа у відповіді в якій буде віддаватися масив доступних сервісів.
204 +
205 +Значення за замовченням {{code language="none"}}methods{{/code}}. Може мати будь-яке значення типу рядок.
206 +
205 205  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
206 206  ufo_json_rpc:
207 207   docs:
208 - project_name: 'My Project'
209 - project_description: 'My project description'
210 - project_version: '1.0'
211 - # Optional response details
212 - async_dsn_info: false # Provide information about API that work asynchronously
213 - validations:
214 - symfony_asserts: false # Indicates if an array of Symfony validation constraints is used
210 + key_for_methods: methods
211 +{{/code}}
215 215  
213 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
214 +ufo_json_rpc:
215 + docs:
216 + key_for_methods: services
216 216  {{/code}}
217 217  
219 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
220 +ufo_json_rpc:
221 + docs:
222 + key_for_methods: some_custom_key
223 +{{/code}}
224 +
225 +=== Параметр {{code language="none"}}async_dsn_info{{/code}} ===
226 +
227 +Відповідає за відображення в документації інформації про асинхронний транспорт.
228 +
229 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
230 +ufo_json_rpc:
231 + async_dsn_info: true # or false
232 +{{/code}}
233 +
218 218  ==== **Приклад документації ** ====
219 219  
220 220  {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
... ... @@ -280,14 +280,8 @@
280 280  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
281 281  ufo_json_rpc:
282 282   docs:
283 - project_name: 'My Project'
284 - project_description: ''
285 - project_version: null
286 - # Optional response details
287 - async_dsn_info: false # Provide information about API that work asynchronously
288 - validations:
289 - symfony_asserts: false # Indicates if an array of Symfony validation constraints is used
290 -
299 + json_schema: true
300 + symfony_asserts: true
291 291  {{/code}}
292 292  
293 293  ==== **Приклад документації ** ====
... ... @@ -300,78 +300,130 @@
300 300  
301 301  {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
302 302  {
303 - "openrpc":"1.2.6",
304 - "info":{
305 - "title":"My Project",
306 - "description":"My project description",
307 - "contact":{
308 - "name":"ufo-tech/json-rpc-bundle",
309 - "url":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
310 - },
311 - "license":{
312 - "name":"MIT"
313 - },
314 - "version":"1.0"
315 - },
316 - "servers":[
317 - {
318 - "url":"https://mysite.com/api",
319 - "description":"Json-RPC api server from UFO Tec\n\nUFO Tech, or Universal Flexible Open Technologies, is an initiative aimed at providing PHP developers with tools to create complex yet user-friendly solutions for modern web applications and service-oriented architectures.",
320 - "name":"UFO Json-RPC Server v.7.0.0",
321 - "x-method":"POST",
322 - "x-ufo":{
323 - "envelop":"JSON-RPC-2.0/UFO-RPC-7.0.0",
324 - "transport":{
325 - "sync":{
326 - "scheme":"https",
327 - "host":"mysite.com",
328 - "path":"/api",
329 - "method":"POST"
330 - },
331 - "async":{
332 - "scheme":"amqp",
333 - "user":"{user}",
334 - "pass":"{pass}",
335 - "host":"mysite.com",
336 - "port":5672,
337 - "path":"/%2f/json-rpc"
338 - }
313 + "envelope": "JSON-RPC-2.0/UFO-RPC-6",
314 + "contentType": "application/json",
315 + "description": "",
316 + "transport": {
317 + "sync": {
318 + "scheme": "https",
319 + "host": "example.com",
320 + "path": "/api",
321 + "method": "POST"
322 + }
323 + },
324 + "methods": {
325 + "getUserNameByUuid": {
326 + "name": "getUserNameByUuid",
327 + "description": "Get username by id",
328 + "parameters": {
329 + "userId": {
330 + "type": "string",
331 + "name": "userId",
332 + "description": "User id in uuid format",
333 + "optional": false
334 + }
339 339   },
340 - "documentation":{
341 - "json-rpc":"https://www.jsonrpc.org/specification",
342 - "ufo-tech/json-rpc-bundle":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
336 + "returns": "string",
337 + "responseFormat": "string",
338 + "json_schema": {
339 + "$schema": "http://json-schema.org/draft-07/schema#",
340 + "type": "object",
341 + "properties": {
342 + "userId": {
343 + "type": "string"
344 + }
345 + },
346 + "required": [
347 + "userId"
348 + ]
349 + },
350 + "symfony_assertions": {
351 + "userId": [
352 + {
353 + "class": "Symfony\\Component\\Validator\\Constraints\\Uuid",
354 + "context": {}
355 + }
356 + ]
343 343   }
344 - }
345 - }
346 - ],
347 - "methods":[
348 - {
349 - "name":"getUserNameByUuid",
350 - "tags":[
351 - {
352 - "name":"App\\Api\\UserApiService"
358 + },
359 + "sendEmail": {
360 + "name": "sendEmail",
361 + "description": "Send mail",
362 + "parameters": {
363 + "email": {
364 + "type": "string",
365 + "name": "email",
366 + "description": "",
367 + "optional": false
368 + },
369 + "subject": {
370 + "type": "string",
371 + "name": "subject",
372 + "description": "",
373 + "optional": false
374 + },
375 + "text": {
376 + "type": "string",
377 + "name": "text",
378 + "description": "",
379 + "optional": false
380 + }
381 + },
382 + "returns": "boolean",
383 + "responseFormat": "boolean",
384 + "json_schema": {
385 + "$schema": "http://json-schema.org/draft-07/schema#",
386 + "type": "object",
387 + "properties": {
388 + "email": {
389 + "type": "string",
390 + "format": "email"
391 + },
392 + "subject": {
393 + "type": "string",
394 + "minLength": 1,
395 + "maxLength": 100
396 + },
397 + "text": {
398 + "type": "string",
399 + "minLength": 10
400 + }
401 + },
402 + "required": [
403 + "email",
404 + "subject",
405 + "text"
406 + ]
407 + },
408 + "symfony_assertions": {
409 + "email": [
410 + {
411 + "class": "Symfony\\Component\\Validator\\Constraints\\Email",
412 + "context": {}
413 + }
414 + ],
415 + "subject": [
416 + {
417 + "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
418 + "context": {}
419 + },
420 + {
421 + "class": "Symfony\\Component\\Validator\\Constraints\\Length",
422 + "context": {}
423 + }
424 + ],
425 + "text": [
426 + {
427 + "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
428 + "context": {}
429 + },
430 + {
431 + "class": "Symfony\\Component\\Validator\\Constraints\\Length",
432 + "context": {}
433 + }
434 + ]
353 353   }
354 - ],
355 - "summary":"Get username by id",
356 - "params":[
357 - {
358 - "name":"userId",
359 - "description":"User Id format uuid",
360 - "required":true,
361 - "schema":{
362 - "type":"string"
363 - },
364 - "x-ufo-assertions": "new Assert\\Uuid()"
365 - }
366 - ],
367 - "result":{
368 - "name":"string",
369 - "description":"User Name",
370 - "schema":{
371 - "type":"string"
372 - }
373 - }
374 - }
375 - ]
436 + }
437 + }
376 376  }
377 377  {{/code}}