...
Мы записываем базисы путей, и где они определяются:
| Code Block | ||||
|---|---|---|---|---|
| ||||
get:
tags:
- portal
summary: Список статей
parameters:
- name: pageRows
in: query
description: Количество записей
schema:
type: integer
default: 25
- name: sort
in: query
description: Сортировка по одному параметру выше
schema:
type: string
- name: pg
in: query
description: Работает вместе с pageRows, параметр отвечает с какой записи начинать возвращать в запросе
schema:
type: integer
default: 0
responses:
200:
description: Успешное выполнение
content:
application/json:
schema:
$ref: "../schemas/articlesList.yaml"
security:
- KEY: [ ]
post:
tags:
- portal
summary: Добавление статьи
operationId: addArticlePortal
requestBody:
description: Параметры, которые нужно указать
content:
application/json:
schema:
$ref: "../schemas/articleAddRequest.yaml"
required: true
responses:
200:
description: успешное выполнение
content:
application/json:
schema:
$ref: "../schemas/articleAddResponse.yaml"
security:
- KEY: [ ] |
К стандарту OpenAPI, обязательно изучите другие параметры.
Повсюду, где можно определить schema - стараемся делить в ../schemas/*.
Пример articlesList:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
type: object
properties:
list:
type: array
items:
$ref: "./article.yaml"
total:
type: number
example: 173 |
Поскольку это стандартный список в системе, то лучше item отдельно делить в схему.
Это позволит переиспользовать его в пути с одиничным определением /portal/articles/{ID}
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
type: object
properties:
id:
type: integer
example: 164
archive:
type: integer
example: 0
addressFlat:
type: string
example: "4"
buildId:
type: number
example: 8
content:
type: string
example: "<p>Новая Open Source версия биллинга!</p>\n\n\n\n<p>Полный список новинок, исправлений и улучшений биллинга к новому релизу!</p>"
date:
type: string
example: "2023-01-27"
deeplink:
type: integer
example: 1
districtId:
type: string
example: "8"
domainId:
type: integer
example: 0
endDate:
type: string
example: ""
etimestamp:
type: integer
example: 0
gid:
type: integer
example: 0
importance:
type: integer
example: 0
name:
type: string
example: "Releases"
onMainPage:
type: integer
example: 0
permalink:
type: string
example: "releases-abills-095-blackout"
picture:
type: string
example: "https://demo.abills.net.ua:9443/images/attach/portal/13863233.jpg"
portalMenuId:
type: integer
example: 8
shortDescription:
type: string
example: "Встречайте новый релиз 2023"
stName:
type: string
example: ""
status:
type: integer
example: 1
streetId:
type: integer
example: 0
tagName:
type: string
example: ""
tags:
type: integer
example: 0
title:
type: string
example: "Релиз ABillS 0.95 Blackout"
url:
type: string
example: "https://demo.abills.net.ua:9443/?article=release-abills-095-blackout"
utimestamp:
type: integer
example: 1674815301 |
И в конце запускаем misc/api/generate_docs.pl, и проверяем bundle_admin.yaml.
И поздравляем, вы полностью разработали и описали ADMIN API для модуля.
USER API
Создание роутов
Если нужно USER API, заполняем и это:
...