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

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

Підсумок

Подробиці

Властивості сторінки
Вміст
... ... @@ -16,37 +16,28 @@
16 16  
17 17  Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
18 18  
19 -== Параметр {{code language="none"}}protected_methods{{/code}} ==
19 +== Параметри {{code language="none"}}protected_api{{/code}} та {{code language="none"}}protected_doc{{/code}} (boolean) ==
20 20  
21 21  (% class="wikigeneratedid" %)
22 -Цей параметр приймає масив назв http методів, які мають бути захищені.
22 +Ці параметри вказує чи мають бути захищені API методи та документація, відповідно.
23 23  
24 24  (% class="wikigeneratedid" %)
25 -За замовченням ввімкнут захист лише для методу POST. Ви можете:
25 +За замовченням апі методи захищені, а документація відкрита.
26 26  
27 -* вказати пустий масив {{code language="none"}}[]{{/code}} щоб зробити API повністю відкритим
28 -
29 29  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
30 30  ufo_json_rpc:
31 31   security:
32 - protected_methods: []
30 + protected_api: true # Protection API requests
31 + protected_doc: false # Protection API documentation
33 33  {{/code}}
34 34  
35 -* вказати додатково захист для методу GET, що зробить запит документації недоступним без токену в заголовках запиту
34 +(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_api{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
36 36  
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 -
45 45  Перш за все, треба визначитися з назвою токену.
46 46  
47 -== Параметр {{code language="none"}}token_key_in_header{{/code}} ==
38 +== Параметр {{code language="none"}}token_name{{/code}} ==
48 48  
49 -Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_key_in_header: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
40 +Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_name: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
50 50  
51 51  {{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
52 52  Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
... ... @@ -66,8 +66,16 @@
66 66  
67 67  
68 68  
69 -== Параметр {{code language="none"}}clients_tokens{{/code}} ==
70 70  
61 +
62 +
63 +
64 +
65 +
66 +
67 +
68 +Параметр {{code language="none"}}clients_tokens{{/code}}
69 +
71 71  Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
72 72  
73 73  Тут є певна варіативність.
... ... @@ -87,8 +87,7 @@
87 87  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
88 88  ufo_json_rpc:
89 89   security:
90 - protected_methods: ['GET', 'POST']
91 - token_key_in_header: 'Ufo-RPC-Token'
89 + token_name: 'Ufo-RPC-Token'
92 92   clients_tokens:
93 93   - 'ClientTokenExample' # hardcoded token example. Importantly!!! Replace or delete it!
94 94  
... ... @@ -109,7 +109,6 @@
109 109  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
110 110  ufo_json_rpc:
111 111   security:
112 - protected_methods: ['GET', 'POST']
113 113   token_key_in_header: 'Ufo-RPC-Token'
114 114   clients_tokens:
115 115   - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
... ... @@ -192,45 +192,32 @@
192 192  
193 193  = Блок {{code language="none"}}docs{{/code}} =
194 194  
195 -Це блок який налаштовує генерацію документації коли ви робите GET запит на RPC Server
192 +Цей блок налаштовує деякі параметри генерації документації коли ви робите GET запит на RPC Server.
196 196  
197 -== Секція {{code language="none"}}response{{/code}} ==
194 +(% class="box infomessage" %)
195 +(((
196 +Починаючи з версії 7, JsonRpcBundle генерує API документацію, що відповідає специфікації [[OpenRpc>>https://spec.open-rpc.org/]]
197 +)))
198 198  
199 -Містить налаштування, що відповідають за вміст відповіді.
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]])
200 200  
201 -=== Параметр {{code language="none"}}key_for_methods{{/code}} ===
202 -
203 -Цей параметр дозволяє вказати назву ключа у відповіді в якій буде віддаватися масив доступних сервісів.
204 -
205 -Значення за замовченням {{code language="none"}}methods{{/code}}. Може мати будь-яке значення типу рядок.
206 -
207 207  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
208 208  ufo_json_rpc:
209 209   docs:
210 - key_for_methods: methods
211 -{{/code}}
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
212 212  
213 -{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
214 -ufo_json_rpc:
215 - docs:
216 - key_for_methods: services
217 217  {{/code}}
218 218  
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 -
234 234  ==== **Приклад документації ** ====
235 235  
236 236  {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
... ... @@ -296,8 +296,14 @@
296 296  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
297 297  ufo_json_rpc:
298 298   docs:
299 - json_schema: true
300 - symfony_asserts: true
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 +
301 301  {{/code}}
302 302  
303 303  ==== **Приклад документації ** ====
... ... @@ -310,130 +310,78 @@
310 310  
311 311  {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
312 312  {
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 - }
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 + }
335 335   },
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 - ]
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"
357 357   }
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 - ]
344 + }
345 + }
346 + ],
347 + "methods":[
348 + {
349 + "name":"getUserNameByUuid",
350 + "tags":[
351 + {
352 + "name":"App\\Api\\UserApiService"
435 435   }
436 - }
437 - }
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 + ]
438 438  }
439 439  {{/code}}