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

Остання зміна 2024/07/11 11:49 автором Ashterix

Від 2.2 до 2.1 Від 5.1 до 4.1

Від версії 4.1

редаговано Ashterix
дата 2024/07/11 11:41

Змінити коментар: Немає коментарів для цієї версії

До версії 2.2

редаговано Ashterix
дата 2024/07/11 10:05

Змінити коментар: Немає коментарів для цієї версії

Необроблений
Надані

Підсумок

Властивості сторінки (1 змінено, 0 додано, 0 видалено)

Подробиці

Властивості сторінки

Вміст

@@ -16,28 +16,37 @@
  Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
--== Параметри {{code language="none"}}protected_api{{/code}} та {{code language="none"}}protected_doc{{/code}} (boolean) ==
++== Параметр {{code language="none"}}protected_methods{{/code}} ==
  (% class="wikigeneratedid" %)
--Ці параметри вказує чи мають бути захищені API методи та документація, відповідно.
++Цей параметр приймає масив назв http методів, які мають бути захищені.
  (% class="wikigeneratedid" %)
--За замовченням апі методи захищені, а документація відкрита.
++За замовченням ввімкнут захист лише для методу POST. Ви можете:
++* вказати пустий масив {{code language="none"}}[]{{/code}} щоб зробити API повністю відкритим
++
  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
  ufo_json_rpc:
      security:
--        protected_api: true     # Protection API requests
--        protected_doc: false    # Protection API documentation
++        protected_methods: []
  {{/code}}
--(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_api{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
++* вказати додатково захист для методу GET, що зробить запит документації недоступним без токену в заголовках запиту
++{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
++ufo_json_rpc:
++    security:
++        protected_methods: ['GET', 'POST']
++{{/code}}
++
++(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_methods{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
++
  Перш за все, треба визначитися з назвою токену.
--== Параметр {{code language="none"}}token_name{{/code}} ==
++== Параметр {{code language="none"}}token_key_in_header{{/code}} ==
--Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_name: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
++Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_key_in_header: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
  {{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
  Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
@@ -57,17 +57,8 @@
++== Параметр {{code language="none"}}clients_tokens{{/code}} ==
--
--
--
--
--
--
--
--
--Параметр {{code language="none"}}clients_tokens{{/code}}
--
  Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
  Тут є певна варіативність.
@@ -87,7 +87,8 @@
  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
  ufo_json_rpc:
      security:
--        token_name: 'Ufo-RPC-Token'
++        protected_methods: ['GET', 'POST']
++        token_key_in_header: 'Ufo-RPC-Token'
          clients_tokens:
              - 'ClientTokenExample'  # hardcoded token example. Importantly!!! Replace or delete it!
@@ -108,6 +108,7 @@
  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
  ufo_json_rpc:
      security:
++        protected_methods: ['GET', 'POST']
          token_key_in_header: 'Ufo-RPC-Token'
          clients_tokens:
              - '%env(resolve:TOKEN_FOR_APP_1)%'   # token example from .env.local
@@ -190,34 +190,76 @@
  = Блок {{code language="none"}}docs{{/code}} =
--Цей блок налаштовує деякі параметри генерації документації коли ви робите GET запит на RPC Server.
++Це блок який налаштовує генерацію документації коли ви робите GET запит на RPC Server
--(% class="box infomessage" %)
--(((
--Починаючи з версії 7, JsonRpcBundle генерує API документацію, що відповідає специфікації [[OpenRpc>>https://spec.open-rpc.org/]]
--)))
++== Секція {{code language="none"}}response{{/code}} ==
--* {{code language="none"}}project_name{{/code}}: Назва проєкту, що буде відображена в документації
--* {{code language="none"}}project_description{{/code}}: Опис проєкту
--* {{code language="none"}}project_version{{/code}}: Поточна версія вашого API
--* {{code language="none"}}async_dsn_info{{/code}}: Відповідає за відображення в документації інформації про асинхронний транспорт
--* (% id="cke_bm_826282S" style="display:none" %){{code language="none"}}validations.symfony_asserts{{/code}}(%%): <bool> Відповідає за відображення рядку очікувань валідації для параметра (якщо ви використовуєте [[валідацію>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]])
++Містить налаштування, що відповідають за вміст відповіді.
++=== Параметр {{code language="none"}}key_for_methods{{/code}} ===
++
++Цей параметр дозволяє вказати назву ключа у відповіді в якій буде віддаватися масив доступних сервісів.
++
++Значення за замовченням {{code language="none"}}methods{{/code}}. Може мати будь-яке значення типу рядок.
++
  {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
  ufo_json_rpc:
      docs:
--        project_name: 'My Project'
--        project_description: 'My project description'
--        project_version: '1.0'
--        # Optional response details
--        async_dsn_info:  false          # Provide information about API that work asynchronously
--        validations:
--            symfony_asserts: false      # Indicates if an array of Symfony validation constraints is used
++        key_for_methods: methods
++{{/code}}
++{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
++ufo_json_rpc:
++    docs:
++        key_for_methods: services
  {{/code}}
++{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
++ufo_json_rpc:
++    docs:
++        key_for_methods: some_custom_key
++{{/code}}
++
++=== Параметр {{code language="none"}}async_dsn_info{{/code}} ===
++
++Відповідає за відображення в документації інформації про асинхронний транспорт.
++
++{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
++ufo_json_rpc:
++    async_dsn_info: true # or false
++{{/code}}
++
++==== **Приклад документації ** ====
++
++{{code language="json" layout="LINENUMBERS" title="GET: /api"}}
++{
++    "envelope": "JSON-RPC-2.0/UFO-RPC-6",
++    "contentType": "application/json",
++    "description": "",
++    "transport": {
++        "sync": {
++            "scheme": "http",
++            "host": "example.com",
++            "path": "/api",
++            "method": "POST"
++        },
++        "async": {
++            "scheme": "amqp",
++            "user": "{user}",
++            "pass": "{pass}",
++            "host": "async_rabbit",
++            "port": 5672,
++            "path": "/%2f/json-rpc"
++        }
++    },
++    "methods": {
++        ...
++    }
++}
++{{/code}}
++
  {{info}}
--Не переймайтеся щодо безпеки ваших авторизаційних даних, що містяться в DSN.
++Не переймайтеся щодо безпеки ваших авторизаційних даних. що містяться в DSN.
  Документатор побудований таким чином, що перед виводом інформації про DSN він видаляє дані про користувача і його пароль, а також інші секретні дані, як то токени, секретні ключі, тощо.
@@ -237,82 +237,159 @@
  {{/code}}
  {{/info}}
--=== Приклад документації ===
++=== Параметр {{code language="none"}}validations{{/code}} ===
++Відповідає за відображення в документації методів додаткових блоків, що вказують на вимоги до валідації даних.
++
++Наразі цей блок має два можливих налаштування:
++
++* {{code language="none"}}json_schema: <bool>{{/code}}
++* {{code language="none"}}symfony_asserts: <bool>{{/code}}
++
++У всіх опцій в цьому параметрі значення за замовченням {{code language="none"}}false{{/code}}, тобто ці блоки не будуть відображатися в документації.
++Якщо ви потребуєте якийсь з цих блоків інформації при запиті документації, то встановіть значення в {{code language="none"}}true{{/code}}.
++
++{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
++ufo_json_rpc:
++    docs:
++        json_schema: true
++        symfony_asserts: true
++{{/code}}
++
++==== **Приклад документації ** ====
++
++(% class="box infomessage" %)
++(((
++В цьому прикладі я видалив вміст обʼєктів symfony_assertions для спрощення прикладу.
++Детальніше про валідацію методів дивись сторінку **[[Валідація процедур>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]]**
++)))
++
  {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
  {
--   "openrpc":"1.2.6",
--   "info":{
--      "title":"My Project",
--      "description":"My project description",
--      "contact":{
--         "name":"ufo-tech/json-rpc-bundle",
--         "url":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
--      },
--      "license":{
--         "name":"MIT"
--      },
--      "version":"1.0"
--   },
--   "servers":[
--      {
--         "url":"https://mysite.com/api",
--         "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.",
--         "name":"UFO Json-RPC Server v.7.0.0",
--         "x-method":"POST",
--         "x-ufo":{
--            "envelop":"JSON-RPC-2.0/UFO-RPC-7.0.0",
--            "transport":{
--               "sync":{
--                  "scheme":"https",
--                  "host":"mysite.com",
--                  "path":"/api",
--                  "method":"POST"
--               },
--               "async":{
--                  "scheme":"amqp",
--                  "user":"{user}",
--                  "pass":"{pass}",
--                  "host":"mysite.com",
--                  "port":5672,
--                  "path":"/%2f/json-rpc"
--               }
++    "envelope": "JSON-RPC-2.0/UFO-RPC-6",
++    "contentType": "application/json",
++    "description": "",
++    "transport": {
++        "sync": {
++            "scheme": "https",
++            "host": "example.com",
++            "path": "/api",
++            "method": "POST"
++        }
++    },
++    "methods": {
++        "getUserNameByUuid": {
++            "name": "getUserNameByUuid",
++            "description": "Get username by id",
++            "parameters": {
++                "userId": {
++                    "type": "string",
++                    "name": "userId",
++                    "description": "User id in uuid format",
++                    "optional": false
++                }
              },
--            "documentation":{
--               "json-rpc":"https://www.jsonrpc.org/specification",
--               "ufo-tech/json-rpc-bundle":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
++            "returns": "string",
++            "responseFormat": "string",
++            "json_schema": {
++                "$schema": "http://json-schema.org/draft-07/schema#",
++                "type": "object",
++                "properties": {
++                    "userId": {
++                        "type": "string"
++                    }
++                },
++                "required": [
++                    "userId"
++                ]
++            },
++            "symfony_assertions": {
++                "userId": [
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\Uuid",
++                        "context": {}
++                    }
++                ]
              }
--         }
--      }
--   ],
--   "methods":[
--      {
--         "name":"getUserNameByUuid",
--         "tags":[
--            {
--               "name":"App\\Api\\UserApiService"
++        },
++        "sendEmail": {
++            "name": "sendEmail",
++            "description": "Send mail",
++            "parameters": {
++                "email": {
++                    "type": "string",
++                    "name": "email",
++                    "description": "",
++                    "optional": false
++                },
++                "subject": {
++                    "type": "string",
++                    "name": "subject",
++                    "description": "",
++                    "optional": false
++                },
++                "text": {
++                    "type": "string",
++                    "name": "text",
++                    "description": "",
++                    "optional": false
++                }
++            },
++            "returns": "boolean",
++            "responseFormat": "boolean",
++            "json_schema": {
++                "$schema": "http://json-schema.org/draft-07/schema#",
++                "type": "object",
++                "properties": {
++                    "email": {
++                        "type": "string",
++                        "format": "email"
++                    },
++                    "subject": {
++                        "type": "string",
++                        "minLength": 1,
++                        "maxLength": 100
++                    },
++                    "text": {
++                        "type": "string",
++                        "minLength": 10
++                    }
++                },
++                "required": [
++                    "email",
++                    "subject",
++                    "text"
++                ]
++            },
++            "symfony_assertions": {
++                "email": [
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\Email",
++                        "context": {}
++                    }
++                ],
++                "subject": [
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
++                        "context": {}
++                    },
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\Length",
++                        "context": {}
++                    }
++                ],
++                "text": [
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
++                        "context": {}
++                    },
++                    {
++                        "class": "Symfony\\Component\\Validator\\Constraints\\Length",
++                        "context": {}
++                    }
++                ]
              }
--         ],
--         "summary":"Get username by id",
--         "params":[
--            {
--               "name":"userId",
--               "description":"User Id format uuid",
--               "required":true,
--               "schema":{
--                  "type":"string"
--               },
--               "x-ufo-assertions": "new Assert\\Uuid()"
--            }
--         ],
--         "result":{
--            "name":"string",
--            "description":"User Name",
--            "schema":{
--               "type":"string"
--            }
--         }
--      }
--   ]
++        }
++    }
  }
  {{/code}}

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

Підсумок

Подробиці

Навігація

Дочірні Cторінки

Нещодавно переглянуті