denozord/EvoBGP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 131 Wiki Activity

docs: убрать типографское тире и невидимый Unicode из текстов API

Browse Source 
Made-with: Cursor
This commit is contained in:
Denozordec
2026-04-04 00:31:56 +07:00
parent a754e1d9f2
commit fbe9cd3f3c
4 changed files with 50 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/OPENAPI-GITEA.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Как смотреть API-документацию (Gitea без встроенного OpenAPI)
В веб-интерфейсе Gitea файлы из репозитория показываются **как исходный текст** (в т.ч. HTML) — это нормально: страница в браузере **не выполняется** из просмотра кода.
В веб-интерфейсе Gitea файлы из репозитория показываются **как исходный текст** (в т.ч. HTML) - это нормально: страница в браузере **не выполняется** из просмотра кода.
## Самый простой способ
@@ -31,4 +31,4 @@
Или вручную: `npx @redocly/cli@1 build-docs docs/openapi.yaml -o docs/openapi.html`, затем встроить `redoc.standalone.js` по аналогии со скриптом.
Источник правды по контракту API — **`docs/openapi.yaml`** (OpenAPI 3.1).
Источник правды по контракту API - **`docs/openapi.yaml`** (OpenAPI 3.1).
docs/evobgp-api-sketches.md
+11 -11
View File
@@ -1,6 +1,6 @@
# EvoBGP — наброски HTTP API
# EvoBGP - наброски HTTP API
**Статус:** черновик для согласования; не спецификация реализации. Базовый префикс: **`/v1`**. Модель данных и термины — в архитектурном плане (модули, `bgp_speaker`, `config_revision`, `job_audit`).
**Статус:** черновик для согласования; не спецификация реализации. Базовый префикс: **`/v1`**. Модель данных и термины - в архитектурном плане (модули, `bgp_speaker`, `config_revision`, `job_audit`).
---
@@ -10,13 +10,13 @@
|------|---------------------|
| **Аутентификация** | Заголовок `Authorization: Bearer <api_key>` или mTLS на edge; ключи привязаны к tenant и роли. |
| **Multi-tenant** | Все сущности в скоупе tenant: либо из ключа, либо явный префикс `X-Tenant-Id` (только для супер-ролей). |
| **Идентификаторы** | UUID v7 или ULID в URL; в JSON — строки. |
| **Идентификаторы** | UUID v7 или ULID в URL; в JSON - строки. |
| **Время** | ISO 8601 UTC (`2026-04-03T12:00:00Z`). |
| **Ошибки** | Тело `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail`, `instance`, опционально `errors[]` по полям. |
| **Идемпотентность** | Для мутаций, создающих задачи или побочные эффекты: заголовок `Idempotency-Key` (опционально обязателен для `POST` apply/refresh). |
| **Пагинация** | `?cursor=<opaque>&limit=50` (cursor-based); ответ: `items`, `next_cursor`, `has_more`. |
| **Асинхронные операции** | `202 Accepted`, заголовок `Location: /v1/jobs/{job_id}`; тело `{ "job_id", "status": "queued" }`. |
| **Версионирование** | Несовместимые изменения — новый префикс `/v2`. |
| **Версионирование** | Несовместимые изменения - новый префикс `/v2`. |
---
@@ -34,7 +34,7 @@
### Связь с продуктом
**ASN / CDN / DOMAINS / IP-диапазоны** в продуктовой формулировке — это **четыре вида модулей**. Поле **`type`** в `POST /v1/modules` выбирает вид: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS` или **`IP_RANGES`**. Дочерние ресурсы: **`as-entries`**, **`cdn-sources`**, **`domain-entries`** — как раньше; **`ip-range-entries`** — статические **CIDR + `community_id`** (без ASN и без URL). **`module_id`** в пути — идентификатор **конкретного экземпляра** модуля, а не имя типа.
**ASN / CDN / DOMAINS / IP-диапазоны** в продуктовой формулировке - это **четыре вида модулей**. Поле **`type`** в `POST /v1/modules` выбирает вид: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS` или **`IP_RANGES`**. Дочерние ресурсы: **`as-entries`**, **`cdn-sources`**, **`domain-entries`** - как раньше; **`ip-range-entries`** - статические **CIDR + `community_id`** (без ASN и без URL). **`module_id`** в пути - идентификатор **конкретного экземпляра** модуля, а не имя типа.
Типы: `AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS`, `IP_RANGES` (как в плане).
@@ -44,7 +44,7 @@
| `POST` | `/v1/modules` | Создать модуль. |
| `GET` | `/v1/modules/{module_id}` | Детали модуля. |
| `PATCH` | `/v1/modules/{module_id}` | Частичное обновление (расписание, DoH, приоритет, `enabled`). |
| `DELETE` | `/v1/modules/{module_id}` | Мягкое удаление или `enabled=false` — зафиксировать в плане реализации. |
| `DELETE` | `/v1/modules/{module_id}` | Мягкое удаление или `enabled=false` - зафиксировать в плане реализации. |
**CDN-источники модуля**
@@ -81,7 +81,7 @@
| Метод | Путь | Описание |
|-------|------|----------|
| `POST` | `/v1/modules/{module_id}/refresh` | Запуск ingest для модуля (CDN / DoH / AS по типу). Для **`IP_RANGES`** обычно **не требуется** (данные только в БД); возможен **`204`** / no-op или отказ **`400`**, если тип не поддерживает refresh — зафиксировать в реализации. |
| `POST` | `/v1/modules/{module_id}/refresh` | Запуск ingest для модуля (CDN / DoH / AS по типу). Для **`IP_RANGES`** обычно **не требуется** (данные только в БД); возможен **`204`** / no-op или отказ **`400`**, если тип не поддерживает refresh - зафиксировать в реализации. |
**Пример тела создания модуля (набросок)**
@@ -107,7 +107,7 @@
| Метод | Путь | Описание |
|-------|------|----------|
| `GET` | `/v1/doh-profiles` | Список. |
| `POST` | `/v1/doh-profiles` | Создать (URL, таймауты; секрет — ссылка на vault id или отдельный `POST .../secret`). |
| `POST` | `/v1/doh-profiles` | Создать (URL, таймауты; секрет - ссылка на vault id или отдельный `POST .../secret`). |
| `GET` | `/v1/doh-profiles/{id}` | Детали (без раскрытия секрета). |
| `PATCH` | `/v1/doh-profiles/{id}` | Обновить. |
| `DELETE` | `/v1/doh-profiles/{id}` | Удалить, если не используется модулями. |
@@ -163,7 +163,7 @@
| Метод | Путь | Описание |
|-------|------|----------|
| `GET` | `/v1/revisions/{a}/diff/{b}` | Diff префиксов / метаданных (формат — зафиксировать: JSON patch или табличный). |
| `GET` | `/v1/revisions/{a}/diff/{b}` | Diff префиксов / метаданных (формат - зафиксировать: JSON patch или табличный). |
---
@@ -221,7 +221,7 @@
|-------|------|----------|
| `GET` | `/v1/speakers/{speaker_id}/revisions/latest` | Указатель на последнюю опубликованную ревизию для ноды. |
| `GET` | `/v1/speakers/{speaker_id}/bundle/{revision_id}` | Скачивание подписанного бандла (архив + `manifest.json` + подпись). |
| `POST` | `/v1/nodes/enroll` | Регистрация ноды (обмен ключами, привязка к `speaker_id`) — детали протокола отдельно. |
| `POST` | `/v1/nodes/enroll` | Регистрация ноды (обмен ключами, привязка к `speaker_id`) - детали протокола отдельно. |
Заголовки для бандла: `Content-Type: application/octet-stream` или multipart; контроль целостности по `manifest` (SHA-256) и подписи (например Ed25519).
@@ -264,7 +264,7 @@
|------------|----------------|
| REST, jobs | §1, §10 |
| refresh, apply, rollback, preview, `IP_RANGES` | §3, §8, §9 |
| peers, speakers, communities, DoH | §4–§7 |
| peers, speakers, communities, DoH | §4 - §7 |
| bundle API, нода | §11 |
Файл плана: `.cursor/plans/evobgp_архитектура_0e73ef02.plan.md` (§6 REST API).
docs/openapi.html
+23 -23
View File
File diff suppressed because one or more lines are too long
docs/openapi.yaml
+14 -14
View File
@@ -5,9 +5,9 @@ info:
description: |
REST API управления префиксами, модулями ingest, ревизиями конфигурации BIRD и задачами (async jobs).
**Соглашения:** префикс `/v1`; идентификаторы — UUID v7 или ULID (строки); время — ISO 8601 UTC.
Ошибки — `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)).
Пагинация списков — `cursor` + `limit`; ответ содержит `items`, `next_cursor`, `has_more`.
**Соглашения:** префикс `/v1`; идентификаторы - UUID v7 или ULID (строки); время - ISO 8601 UTC.
Ошибки - `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)).
Пагинация списков - `cursor` + `limit`; ответ содержит `items`, `next_cursor`, `has_more`.
**Роли** (матрица доступа): `viewer`, `editor`, `operator`, `node`. Нода использует отдельные пути и ключ с ролью `node`.
@@ -24,7 +24,7 @@ tags:
- name: System
description: Liveness, readiness и метаданные сборки. Обычно без чувствительных данных; доступ может быть шире.
- name: Modules
description: Экземпляры модулей префиксов (AS, CDN, домены, статические IP-диапазоны) и вложенные записи. Чтение — viewer+; изменение — editor+.
description: Экземпляры модулей префиксов (AS, CDN, домены, статические IP-диапазоны) и вложенные записи. Чтение - viewer+; изменение - editor+.
- name: DoH profiles
description: Профили DNS-over-HTTPS для модулей типа домены. Секрет в ответах не возвращается.
- name: Communities
@@ -42,7 +42,7 @@ tags:
- name: Node
description: "API для evobgp-node (бандлы ревизий и enrollment). Отдельный ключ или mTLS, роль node."
- name: Settings
description: Глобальные настройки и feature flags; изменение — только operator.
description: Глобальные настройки и feature flags; изменение - только operator.
security:
- bearerAuth: []
@@ -563,7 +563,7 @@ components:
type: integer
bgp_speaker_id:
type: ["string", "null"]
description: "`null` — политика для всех спикеров."
description: "`null` - политика для всех спикеров."
additionalProperties: true
BgpSpeaker:
@@ -600,7 +600,7 @@ components:
PrefixSnapshotItem:
type: object
description: Элемент материализованного снимка префиксов (детали — по реализации).
description: Элемент материализованного снимка префиксов (детали - по реализации).
additionalProperties: true
Job:
@@ -684,7 +684,7 @@ components:
RevisionDiff:
type: object
description: |
Сравнение двух ревизий. Конкретный формат (JSON Patch, табличный diff и т.д.) задаётся реализацией — контракт может уточняться.
Сравнение двух ревизий. Конкретный формат (JSON Patch, табличный diff и т.д.) задаётся реализацией - контракт может уточняться.
additionalProperties: true
NodeEnrollRequest:
@@ -878,7 +878,7 @@ paths:
summary: Создать модуль
description: |
Создаёт экземпляр модуля. Поле `type` задаёт вид (`AS_PREFIXES`, `CDN_CIDRS`, `DOMAINS`, `IP_RANGES`).
`module_id` в других путях — идентификатор экземпляра, не имя типа.
`module_id` в других путях - идентификатор экземпляра, не имя типа.
operationId: createModule
parameters:
- $ref: "#/components/parameters/TenantId"
@@ -959,7 +959,7 @@ paths:
delete:
tags: [Modules]
summary: Удалить модуль
description: Мягкое удаление или перевод в `enabled=false` — конкретное поведение задаётся реализацией.
description: Мягкое удаление или перевод в `enabled=false` - конкретное поведение задаётся реализацией.
operationId: deleteModule
parameters:
- $ref: "#/components/parameters/IdempotencyKey"
@@ -1391,7 +1391,7 @@ paths:
summary: Запустить ingest
description: |
Запуск обновления данных модуля (CDN / DoH / AS в зависимости от типа).
Для `IP_RANGES` данные обычно только в БД: сервер может вернуть **204** (no-op) или **400**, если refresh не поддерживается — поведение фиксируется в реализации.
Для `IP_RANGES` данные обычно только в БД: сервер может вернуть **204** (no-op) или **400**, если refresh не поддерживается - поведение фиксируется в реализации.
Рекомендуется передавать `Idempotency-Key`.
operationId: postModuleRefresh
parameters:
@@ -1454,7 +1454,7 @@ paths:
post:
tags: [DoH profiles]
summary: Создать DoH-профиль
description: URL и таймауты; секрет — через vault id или отдельный вызов установки секрета.
description: URL и таймауты; секрет - через vault id или отдельный вызов установки секрета.
operationId: createDohProfile
parameters:
- $ref: "#/components/parameters/TenantId"
@@ -1948,7 +1948,7 @@ paths:
operationId: getRevisionPreview
responses:
"200":
description: Текст или структурированное представление — формат задаётся реализацией.
description: Текст или структурированное представление - формат задаётся реализацией.
content:
application/json:
schema:
@@ -2222,7 +2222,7 @@ paths:
summary: Скачать подписанный бандл
description: |
Архив с `manifest.json` и подписью (например Ed25519). Целостность по SHA-256 в манифесте.
`Content-Type` — `application/octet-stream` или multipart; детали — в реализации.
`Content-Type` - `application/octet-stream` или multipart; детали - в реализации.
operationId: getSpeakerBundle
security:
- bearerAuth: []