Вікі-код для 3. Власні API методи

Версія 6.1 додана 2024/05/16 12:25 автором Ashterix

version	line-number	content
5.1	1	{{box cssClass="floatinginfobox" title="Зміст"}}
	2	{{toc/}}
	3	{{/box}}
2.1	4
3.2	5	Ви можете легко додавати власні API методи до RPC сервера.
	6
6.1	7	Для цього вам достатньо в будь-якому місці вашого додатку зробити будь-який клас який має стати API Сервісом, цей клас має реалізувати інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService{{/code}}. Цей інтерфейс не навʼязує класу жодної логіки, він необхідний лише для того, щоб Symfony зрозумів, що має його сприймати як сервіс, що доступний для RPC сервера.
3.2	8
	9	Реалізуйте в вашому класі будь-який публічний метод і він автоматично буде доступний як API Сервіс.
	10
6.1	11	(% id="cke_bm_318406S" style="display:none" %) (%%)Після виконання попередніх вказівок у вас вже будуть доступні нові методи в API. За замовченням назви методів складаються з {{code language="none"}}<className>.<methodName>{{/code}}.
3.2	12
3.5	13	= Іменування класів =
3.2	14
	15	В разі потреби, ви можете створити кілька класів, що будуть доступні як API Сервіси.
6.1	16	Враховуючи їх неймінги {{code language="none"}}<className>.<methodName>{{/code}}, рекомендую підходити до вибору назви методу як до простої вказівки що він робить, а до назви класу як до неймспейсу API методу.
3.2	17
4.1	18	(% class="box successmessage" %)
	19	(((
3.3	20	== Гарна практика ==
3.2	21
	22	Класс //Messenger// містить методи //sendEmail()////, sendSms()//,// //класс// CartResolver //містить методи //addProduct()////, getProducts()//, //calculateDiscount()//
	23
	24	в API будуть доступні методи
	25
	26	* //CartResolver.addProduct//
	27	* //CartResolver.getProducts//
	28	* //CartResolver.calculateDiscount//
	29	* //Messenger.sendEmail//
	30	* //Messenger.sendSms//
	31
	32	Навіть просто поглянувши на назви методів зрозуміло що може робити ваш сервер.
3.4	33
	34	Такий підхід надає можливість використовувати одноіменні методи в різних класах:
	35
3.5	36	* //ProductService.create//
	37	* //ProductService.getName//
	38	* //UserService.create//
	39	* //UserService.getName//
4.1	40	)))
3.2	41
3.7	42	= Простий старт =
3.2	43
	44	Наступний приклад має продемонструвати легкість додавання ваших методів до API.
	45
3.5	46	(% class="row" %)
	47	(((
	48	(% class="col-xs-12 col-sm-6" %)
	49	(((
6.1	50	{{code language="php" layout="LINENUMBERS" title="== Код =="}}
	51	<?php
	52	namespace App\Api\Procedures;
2.1	53
6.1	54	use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
2.1	55
6.1	56	class ExampleApi implements IRpcService
2.1	57	{
6.1	58	public function __construct(
	59	// connecting some dependencies to retrieve data
	60	) {}
	61
	62	public function getUserNameByUuid(
	63	string $userId
	64	): string
	65	{
	66	// some logic get user info by id
	67	return 'some result';
	68	}
	69
	70	public function sendEmail(
	71	string $email,
	72	string $text,
	73	string $subject = 'Message without subject'
	74	): bool
	75	{
	76	// some logic send email
	77	return true;
	78	}
2.1	79	}
6.1	80	{{/code}}
3.2	81
3.8	82	Праворуч приклад документації, що сервер згенерує по цьому класу.
3.7	83
4.1	84	Основна інформація щодо назв параметрів, їх типів та опціональності отримується завдяки (% class="box code" %)ReflectionClass(%%), важливим є порядок аргументів методу, їх typehint.
3.5	85	)))
3.2	86
3.5	87	(% class="col-xs-12 col-sm-6" %)
	88	(((
6.1	89	{{code language="json" layout="LINENUMBERS" title="== Документація =="}}
3.2	90	{
6.1	91	"methods": {
	92	"ExampleApi.getUserNameByUuid": {
	93	"name": "ExampleApi.getUserNameByUuid",
	94	"description": "",
	95	"parameters": {
	96	"userId": {
	97	"type": "string",
	98	"name": "userId",
	99	"description": "",
	100	"optional": false
3.2	101	}
	102	},
6.1	103	"returns": "string",
	104	"responseFormat": "string"
3.2	105	},
6.1	106	"ExampleApi.sendEmail": {
	107	"name": "ExampleApi.sendEmail",
	108	"description": "",
	109	"parameters": {
	110	"email": {
	111	"type": "string",
	112	"name": "email",
	113	"description": "",
	114	"optional": false
3.2	115	},
6.1	116	"text": {
	117	"type": "string",
	118	"name": "text",
	119	"description": "",
	120	"optional": false
3.2	121	},
6.1	122	"subject": {
	123	"type": "string",
	124	"name": "subject",
	125	"description": "",
	126	"optional": true,
	127	"default": "Message without subject"
3.2	128	}
	129	},
6.1	130	"returns": "boolean",
	131	"responseFormat": "boolean"
3.2	132	}
	133	}
	134	}
6.1	135	{{/code}}
3.5	136	)))
	137	)))
	138
3.2	139	Тепер можемо зробити POST запити на обидва нових метода API і подивитися на результат.
	140
3.7	141	== POST запити ==
3.2	142
3.7	143	(% class="row" %)
	144	(((
	145	(% class="col-xs-12 col-sm-6" %)
	146	(((
6.1	147	{{code language="json" layout="LINENUMBERS" title="Request"}}
3.2	148	{
6.1	149	"id": "example_request",
	150	"method": "ExampleApi.getUserNameByUuid",
	151	"params": {
	152	"userId": "1111"
3.2	153	}
	154	}
6.1	155	{{/code}}
3.7	156	)))
3.2	157
3.7	158	(% class="col-xs-12 col-sm-6" %)
	159	(((
6.1	160	{{code language="json"}}
3.2	161	{
6.1	162	"id": "example_request",
	163	"result": "some result",
	164	"jsonrpc": "2.0"
3.2	165	}
6.1	166	{{/code}}
3.2	167
	168
6.1	169
3.7	170
	171	)))
	172	)))
	173
	174	(% class="row" %)
	175	(((
	176	(% class="col-xs-12 col-sm-6" %)
	177	(((
6.1	178	{{code language="json" layout="LINENUMBERS" title="Request"}}
3.2	179	{
6.1	180	"id": "example_request",
	181	"method": "ExampleApi.sendEmail",
	182	"params": {
	183	"email": "user@example.com",
	184	"subject": "This is test mail",
	185	"text": "Hi! This is test send mail by API"
3.2	186	}
	187	}
6.1	188	{{/code}}
3.7	189	)))
3.2	190
3.7	191	(% class="col-xs-12 col-sm-6" %)
	192	(((
6.1	193	{{code language="json"}}
	194	{
	195	"id": "example_request",
	196	"result": true,
	197	"jsonrpc": "2.0"
	198	}
	199	{{/code}}
4.1	200
	201
6.1	202
	203
3.7	204	)))
	205	)))
	206
6.1	207
3.10	208	(% class="box warningmessage" %)
	209	(((
	210	Для спрощення сприйняття документації, всі подальші приклади буду надавати на одному методі (//sendEmail//)
	211	)))
3.7	212
3.10	213	= Опис методів та параметрів =
	214
3.9	215	Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.
3.7	216
3.9	217	Додамо опис методу і параметрів.
3.7	218
3.10	219	(% class="row" %)
	220	(((
	221	(% class="col-xs-12 col-sm-6" %)
	222	(((
6.1	223	{{code language="php" layout="LINENUMBERS" title="== Код =="}}
	224	<?php
	225	// ...
	226	/**
	227	* A method for sending an email message
	228	* @param string $email The email address
	229	* @param string $text Message body
	230	* @param string $subject Optional message subject parameter
	231	* @return bool
	232	*/
	233	public function sendEmail(
	234	string $email,
	235	string $text,
	236	string $subject = 'Message without subject'
	237	): bool
3.10	238	{
6.1	239	// some logic send email
	240	return true;
3.10	241	}
	242
6.1	243	// ...
	244	{{/code}}
	245
3.10	246	Зверніть увагу на документацію, тепер в ній відображається додаткова інформація про метод і його параметри.
	247
	248
	249	)))
	250
	251	(% class="col-xs-12 col-sm-6" %)
	252	(((
6.1	253	{{code language="json" layout="LINENUMBERS" title="== Документація =="}}
3.10	254	{
6.1	255	"methods": {
	256	"ExampleApi.sendEmail": {
	257	"name": "ExampleApi.sendEmail",
	258	"description": "A method for sending an email message",
	259	"parameters": {
	260	"email": {
	261	"type": "string",
	262	"name": "email",
	263	"description": "The email address",
	264	"optional": false
3.10	265	},
6.1	266	"text": {
	267	"type": "string",
	268	"name": "text",
	269	"description": "Message body",
	270	"optional": false
3.10	271	},
6.1	272	"subject": {
	273	"type": "string",
	274	"name": "subject",
	275	"description": "Optional message subject parameter",
	276	"optional": true,
	277	"default": "Message without subject"
3.10	278	}
	279	},
6.1	280	"returns": "boolean",
	281	"responseFormat": "boolean"
3.10	282	}
	283	}
	284	}
6.1	285	{{/code}}
3.10	286	)))
	287	)))
	288
	289	= RPC attributes =
	290
4.1	291	Для більш гнучкого налаштування ваших методів API JsonRpcBundle використовує такий інструмент як [[php атрибути>>url:https://www.php.net/manual/en/language.attributes.overview.php]].
3.10	292
	293	За допомогою спеціалізованих атрибутів ви можете:
	294
	295	* налаштувати псевдоніми для методів;
3.13	296	* вказати формат відповіді для методів (якщо відповідь у вигляді масива, обʼєкта або колекції обʼєктів);
3.10	297	* налаштувати валідацію вхідних параметрів;
	298	* налаштувати кешування відповідей.
	299
3.13	300	Докладніше про ці атрибути:
3.10	301
6.1	302	{{children/}}
4.1	303

Вікі-код для 3. Власні API методи

Навігація

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

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