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

Остання зміна 2024/05/16 12:34 автором 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	(((
7.1	160	{{code language="json" layout="LINENUMBERS" title="Response"}}
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
3.7	169
	170	)))
	171	)))
	172
	173	(% class="row" %)
	174	(((
	175	(% class="col-xs-12 col-sm-6" %)
	176	(((
6.1	177	{{code language="json" layout="LINENUMBERS" title="Request"}}
3.2	178	{
6.1	179	"id": "example_request",
	180	"method": "ExampleApi.sendEmail",
	181	"params": {
	182	"email": "user@example.com",
	183	"subject": "This is test mail",
	184	"text": "Hi! This is test send mail by API"
3.2	185	}
	186	}
6.1	187	{{/code}}
3.7	188	)))
3.2	189
3.7	190	(% class="col-xs-12 col-sm-6" %)
	191	(((
7.1	192	{{code language="json" layout="LINENUMBERS" title="Response"}}
6.1	193	{
	194	"id": "example_request",
	195	"result": true,
	196	"jsonrpc": "2.0"
	197	}
	198	{{/code}}
4.1	199
	200
6.1	201
	202
3.7	203	)))
	204	)))
	205
6.1	206
3.10	207	(% class="box warningmessage" %)
	208	(((
	209	Для спрощення сприйняття документації, всі подальші приклади буду надавати на одному методі (//sendEmail//)
	210	)))
3.7	211
3.10	212	= Опис методів та параметрів =
	213
3.9	214	Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.
3.7	215
3.9	216	Додамо опис методу і параметрів.
3.7	217
3.10	218	(% class="row" %)
	219	(((
	220	(% class="col-xs-12 col-sm-6" %)
	221	(((
6.1	222	{{code language="php" layout="LINENUMBERS" title="== Код =="}}
	223	<?php
	224	// ...
	225	/**
	226	* A method for sending an email message
	227	* @param string $email The email address
	228	* @param string $text Message body
	229	* @param string $subject Optional message subject parameter
	230	* @return bool
	231	*/
	232	public function sendEmail(
	233	string $email,
	234	string $text,
	235	string $subject = 'Message without subject'
	236	): bool
3.10	237	{
6.1	238	// some logic send email
	239	return true;
3.10	240	}
	241
6.1	242	// ...
	243	{{/code}}
	244
3.10	245	Зверніть увагу на документацію, тепер в ній відображається додаткова інформація про метод і його параметри.
	246
	247
	248	)))
	249
	250	(% class="col-xs-12 col-sm-6" %)
	251	(((
6.1	252	{{code language="json" layout="LINENUMBERS" title="== Документація =="}}
3.10	253	{
6.1	254	"methods": {
	255	"ExampleApi.sendEmail": {
	256	"name": "ExampleApi.sendEmail",
	257	"description": "A method for sending an email message",
	258	"parameters": {
	259	"email": {
	260	"type": "string",
	261	"name": "email",
	262	"description": "The email address",
	263	"optional": false
3.10	264	},
6.1	265	"text": {
	266	"type": "string",
	267	"name": "text",
	268	"description": "Message body",
	269	"optional": false
3.10	270	},
6.1	271	"subject": {
	272	"type": "string",
	273	"name": "subject",
	274	"description": "Optional message subject parameter",
	275	"optional": true,
	276	"default": "Message without subject"
3.10	277	}
	278	},
6.1	279	"returns": "boolean",
	280	"responseFormat": "boolean"
3.10	281	}
	282	}
	283	}
6.1	284	{{/code}}
3.10	285	)))
	286	)))
	287
	288	= RPC attributes =
	289
4.1	290	Для більш гнучкого налаштування ваших методів API JsonRpcBundle використовує такий інструмент як [[php атрибути>>url:https://www.php.net/manual/en/language.attributes.overview.php]].
3.10	291
	292	За допомогою спеціалізованих атрибутів ви можете:
	293
	294	* налаштувати псевдоніми для методів;
3.13	295	* вказати формат відповіді для методів (якщо відповідь у вигляді масива, обʼєкта або колекції обʼєктів);
3.10	296	* налаштувати валідацію вхідних параметрів;
	297	* налаштувати кешування відповідей.
	298
3.13	299	Докладніше про ці атрибути:
3.10	300
6.1	301	{{children/}}

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

Навігація

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