api update (v1.0)

Author: nawinds

docs/api/auth.mdx

@@ -4,7 +4,7 @@ title: Auth
 ---
 
 # 1. Auth
-**v0 — System Token Only**
+**v1 — System Token Only**
 
 Для **MVP** авторизации используется **один тип токена** — системный `access_token` с полным доступом ко всему API. Пользовательских аккаунтов и ролей нет.
 

docs/api/cameras.mdx

@@ -3,8 +3,15 @@ sidebar_position: 2
 title: Cameras
 ---
 
+import HighlightParam from '@site/src/components/HighlightParam';
+import HighlightBlock from '@site/src/components/HighlightBlock';
+import JSONHighlight from '@site/src/components/JSONHighlight';
+
 # 2. Cameras
 
+Для работы с камерами обязательно использование [токена авторизации](/docs/api/auth), если в документации конкретного
+эндпоинта не указано иное.
+
 ### 2.1 `GET /cameras`
 
 Возвращает список всех зарегистрированных камер.
@@ -26,6 +33,10 @@ title: Cameras
 **Модель Camera**
 - **camera_id** (`integer`) — уникальный идентификатор камеры.
 - **title** (`string`) — человекочитаемое описание камеры (адрес/куда смотрит).
+- <HighlightParam>**source** (`string`) — URL с видеопотоком камеры (напр. `.m3u8`) или строка для подключения (`rtsp://...`)</HighlightParam>
+- <HighlightParam>**image_width** (`integer`) — ширина изображения видеопотока в пикселях (напр., `1920`)</HighlightParam>
+- <HighlightParam>**image_height** (`integer`) — высота изображения видеопотока в пикселях (напр., `1080`)</HighlightParam>
+- <HighlightParam>**calib** (`json`) — вложенный json-объект с информацией о калибровке и вытягивании изображения с камеры. Сохраняется в одну ячейку таблицы БД. Может быть `null`.</HighlightParam>
 - **latitude** (`float`, `-90..90`) — широта камеры.
 - **longitude** (`float`, `-180..180`) — долгота камеры.
 - **created_at** (`string`, ISO 8601) — дата создания.
@@ -39,11 +50,22 @@ Authorization: Bearer <token>
 ```
 
 **Пример ответа (массив)**
-```json
+<JSONHighlight data={
 [
   {
     "camera_id": 1,
     "title": "Кронверкский просп., парковка напротив ИТМО",
+    "source": "rtsp://...",
+    "image_width": 1920,
+    "image_height": 1080,
+    "calib": {
+          "image_width": 1920, "image_height": 1080,
+          "K": [[1739.237279181759, 0.0, 947.5335576199107],
+                [0.0, 2244.705015334057, 564.6946579168148],
+                [0.0, 0.0, 1.0]],
+          "D": [-0.37062084436192333, 0.05057465862770827, 0.033198096980616335, 0.012812747166936252],
+          "balance": 0.0, "model": "opencv_fisheye_k1k2k3k4"
+    },
     "latitude": 59.955976,
     "longitude": 30.309426,
     "created_at": "2025-10-08T09:12:00Z",
@@ -52,13 +74,17 @@ Authorization: Bearer <token>
   {
     "camera_id": 2,
     "title": "Ломоносова, 9 — двор",
+    "source": "https://... .m3u8",
+    "image_width": 1920,
+    "image_height": 1080,
+    "calib": null,
     "latitude": 59.927366,
     "longitude": 30.338487,
     "created_at": "2025-10-08T09:15:00Z",
     "updated_at": "2025-10-08T09:15:00Z"
   }
-]
-```
+]}
+highlight={["source", "image_width", "image_height", "calib"]}/>
 
 **Ошибки** (в дополнение к [общим](/docs/api/#общие-ошибки))
 
@@ -74,6 +100,10 @@ Authorization: Bearer <token>
 
 **Request body (required)**
 - **title** (`string`, 1..200) — описание камеры (по какому адресу она находится и куда направлена).
+- <HighlightParam>**source** (`string`) — URL с видеопотоком камеры (напр. `.m3u8`) или строка для подключения (`rtsp://...`)</HighlightParam>
+- <HighlightParam>**image_width"** (`integer`) — ширина изображения видеопотока в пикселях (напр., `1920`)</HighlightParam>
+- <HighlightParam>**image_height** (`integer`) — высота изображения видеопотока в пикселях (напр., `1080`)</HighlightParam>
+- <HighlightParam>**calib** (`json`) — вложенный json-объект с информацией о калибровке и вытягивании изображения с камеры. Сохраняется в одну ячейку таблицы БД. Может быть `null`.</HighlightParam>
 - **latitude** (`float`, `-90..90`) — широта камеры.
 - **longitude** (`float`, `-180..180`) — долгота камеры.
 
@@ -89,12 +119,17 @@ POST /api/v0/cameras/new HTTP/1.1
 Host: api.parktrack.live
 Content-Type: application/json
 Authorization: Bearer <token>
-
+```
+<JSONHighlight data={
 {
   "title": "Кронверкский просп., парковка напротив ИТМО",
+  "source": "https://... .m3u8",
+  "image_width": 1920,
+  "image_height": 1080,
+  "calib": null,
   "latitude": 59.955976,
   "longitude": 30.309426
-}
+}} highlight={["source", "image_width", "image_height", "calib"]}/>
 ```
 
 **Пример ответа (201)**
@@ -178,6 +213,10 @@ Content-Type: application/json
 **Response (200)** — объект **Camera**
 - **camera_id** (`integer`) — уникальный идентификатор камеры.
 - **title** (`string`) — человекочитаемое описание камеры (адрес/куда смотрит).
+- <HighlightParam>**source** (`string`) — URL с видеопотоком камеры (напр. `.m3u8`) или строка для подключения (`rtsp://...`)</HighlightParam>
+- <HighlightParam>**image_width"** (`integer`) — ширина изображения видеопотока в пикселях (напр., `1920`)</HighlightParam>
+- <HighlightParam>**image_height** (`integer`) — высота изображения видеопотока в пикселях (напр., `1080`)</HighlightParam>
+- <HighlightParam>**calib** (`json`) — вложенный json-объект с информацией о калибровке и вытягивании изображения с камеры. Сохраняется в одну ячейку таблицы БД. Может быть `null`.</HighlightParam>
 - **latitude** (`float`, `-90..90`) — широта камеры.
 - **longitude** (`float`, `-180..180`) — долгота камеры.
 - **created_at** (`string`, ISO 8601) — дата создания.
@@ -191,16 +230,19 @@ Authorization: Bearer <token>
 ```
 
 **Пример ответа (200)**
-```json
+<JSONHighlight data={
 {
   "camera_id": 1,
   "title": "Кронверкский просп., парковка напротив ИТМО",
+  "source": "https://... .m3u8",
+  "image_width": 1920,
+  "image_height": 1080,
+  "calib": null,
   "latitude": 59.955976,
   "longitude": 30.309426,
   "created_at": "2025-10-08T08:00:00Z",
   "updated_at": "2025-10-08T08:10:00Z"
-}
-```
+}} highlight={["source", "image_width", "image_height", "calib"]}/>
 
 **Ошибки** (в дополнение к [общим](/docs/api/#общие-ошибки))
 | Код     | Тип                     | Описание                                  |
@@ -223,6 +265,10 @@ Authorization: Bearer <token>
 
 **Request body** *(любые из полей ниже; минимум одно поле)*
 - **title** (`string`, 1..200) — описание камеры.
+- <HighlightParam>**source** (`string`) — URL с видеопотоком камеры (напр. `.m3u8`) или строка для подключения (`rtsp://...`)</HighlightParam>
+- <HighlightParam>**image_width"** (`integer`) — ширина изображения видеопотока в пикселях (напр., `1920`)</HighlightParam>
+- <HighlightParam>**image_height** (`integer`) — высота изображения видеопотока в пикселях (напр., `1080`)</HighlightParam>
+- <HighlightParam>**calib** (`json`) — вложенный json-объект с информацией о калибровке и вытягивании изображения с камеры. Сохраняется в одну ячейку таблицы БД. Может быть `null`.</HighlightParam>
 - **latitude** (`float`, `-90..90`) — широта камеры.
 - **longitude** (`float`, `-180..180`) — долгота камеры.
 
@@ -231,6 +277,10 @@ Authorization: Bearer <token>
 **Response (200)** — объект **Camera** (актуальное состояние после обновления)
 - **camera_id** (`integer`)
 - **title** (`string`)
+- <HighlightParam>**source** (`string`)</HighlightParam>
+- <HighlightParam>**image_width"** (`integer`)</HighlightParam>
+- <HighlightParam>**image_height** (`integer`)</HighlightParam>
+- <HighlightParam>**calib** (`json`)</HighlightParam>
 - **latitude** (`float`)
 - **longitude** (`float`)
 - **created_at** (`string`, ISO 8601)
@@ -312,10 +362,99 @@ Authorization: Bearer <token>
 
 **Ошибки**
 
+| Код     | Тип         | Описание                                                                       |
+|---------|-------------|--------------------------------------------------------------------------------|
+| **404** | `Not Found` | Камера с указанным `camera_id` не найдена.                                     |
+| **409** | `Conflict`  | Удаление невозможно из-за зависимостей (есть парковочные зоны с этой камерой). |
+
+**Пример ответа (404)**
+```json
+{
+  "error_description": "Camera not found"
+}
+```
+
+---
+
+<HighlightBlock>
+
+### 2.6 `GET /cameras/next`
+
+Возвращает следующую камеру для очередной детекции автомобилей.
+
+_Примеры:_
+1. Если в прошлый раз этот эндпоинт вернул камеру с id=1, то вернуться должна камера с id=2;
+2. Если всего камер 3 и последний раз возвращалась камера с id=3, то вернуться должна камера с id=1.
+
+**Headers**
+- `Authorization: Bearer <token>`
+
+**Пример запроса**
+```http
+GET /api/v0/cameras/next HTTP/1.1
+Host: api.parktrack.live
+Authorization: Bearer <token>
+```
+
+**Пример ответа 1 (200)**
+```json
+{
+  "camera_id": 1,
+  "source": "https://<path>.m3u8",
+  "image_width": 1920,
+  "image_height": 1080,
+  "calib": "https://<path_to_calib>.json"
+}
+```
+
+**Пример ответа 2 (200)**
+```json
+{
+  "camera_id": 1,
+  "source": "https://<path>.m3u8",
+  "image_width": 1920,
+  "image_height": 1080,
+  "calib": null
+}
+```
+
+**Ошибки**
+
+| Код     | Тип                      | Описание                                                                 |
+|---------|--------------------------|--------------------------------------------------------------------------|
+| **404** | `Not Found`              | Не добавлено ни одной камеры                                             |
+
+**Пример ответа (404)**
+```json
+{
+  "error_description": "No cameras added"
+}
+```
+
+### 2.7 `GET /cameras/<camera_id>/snapshot`
+
+Возвращает кадр из видеопотока камеры (изображение, захваченное из `source` камеры).
+
+**Headers**
+- `Authorization: Bearer <token>`
+
+**Пример запроса**
+```http
+GET /cameras/1/snapshot
+Host: api.parktrack.live
+Authorization: Bearer <token>
+```
+
+**Пример ответа (200)**
+```
+<изображение>
+```
+
+**Ошибки**
+
 | Код     | Тип                      | Описание                                                                 |
 |---------|--------------------------|--------------------------------------------------------------------------|
-| **404** | `Not Found`              | Камера с указанным `camera_id` не найдена.                               |
-| **409** | `Conflict`               | Удаление невозможно из-за зависимостей (если каскадное удаление запрещено). |
+| **404** | `Not Found`              | Такой камеры нет                                                         |
 
 **Пример ответа (404)**
 ```json
@@ -325,3 +464,5 @@ Authorization: Bearer <token>
 ```
 
 ---
+
+</HighlightBlock>

docs/api/index.mdx

@@ -3,20 +3,25 @@ sidebar_position: 2
 title: API
 ---
 
-# General API (v0.0)
+import HighlightParam from '@site/src/components/HighlightParam';
 
+# General API (v1.0)
 
 **Base address:**
-`https://api.parktrack.live/api/v0`
+<HighlightParam>`https://api.parktrack.live`</HighlightParam>
+
+:::warning Обновление API
+17 ноября документация `Cameras`, `Parking Zones` была обновлена, все изменения выделены жёлтым цветом.
+:::
 
 ## Swagger версия
 
 Документация API также доступна в Swagger. Там можно будет поиграться с API и вручную поотправлять запросы, когда API сервер будет готов.
 
 [Открыть документацию в Swagger](https://swagger.parktrack.live)
 
-:::warning Предупреждение
-OpenAPI для Swagger был написан ChatGPT по документации на этом сайте, он почти не проверялся вручную и может содержать неточности или ошибки.
+:::info Предупреждение
+Swagger может содержать неточности или ошибки, приоритетной считать документацию на этом сайте.
 :::
 
 ## Общие ошибки

docs/api/parking_zones.mdx

@@ -3,6 +3,8 @@ sidebar_position: 3
 title: Parking Zones
 ---
 
+import HighlightParam from '@site/src/components/HighlightParam';
+
 # 3. Parking Zones
 
 ## Модель `Zone`
@@ -28,13 +30,16 @@ title: Parking Zones
 
 ---
 
-### 3.1 `GET /zones`
+### 3.1 `GET /zones` (Auth, NoAuth)
 
-Возвращает список всех парковочных зон.
+Возвращает список всех парковочных зон <HighlightParam>(авторизация не обязательна)</HighlightParam>.
 
 **Headers**
 - `Authorization: Bearer <token>`
 
+<HighlightParam>В случае отсутствия токена авторизации возвращаются все поля кроме `camera_id`.</HighlightParam>
+
+
 **Query-параметры (необязательные)**
 - **camera_id** (`integer`) — вернуть зоны только указанной камеры.
 - **min_free_count** (`integer`) — фильтр по минимальному количеству свободных мест в зоне.
@@ -147,16 +152,18 @@ Authorization: Bearer <token>
 
 ---
 
-### 3.3 `GET /zones/<zone_id>`
+### 3.3 `GET /zones/<zone_id>` (Auth, NoAuth)
 
-Возвращает данные о конкретной парковочной зоне.
+Возвращает данные о конкретной парковочной зоне <HighlightParam>(авторизация не обязательна).</HighlightParam>
 
 **Path-параметры**
 - **zone_id** (`integer`, required)
 
 **Headers**
 - `Authorization: Bearer <token>`
 
+<HighlightParam>В случае отсутствия токена авторизации возвращаются все поля кроме `camera_id`.</HighlightParam>
+
 **Response (200)** — объект **Zone**
 ```json
 {

src/components/HighlightBlock/index.js

@@ -0,0 +1,19 @@
+import React from 'react';
+import {useColorMode} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+
+export default function HighlightBlock({children}) {
+  const {colorMode} = useColorMode();
+
+  return (
+    <div
+      className={
+        colorMode === 'dark'
+          ? styles.dark
+          : styles.light
+      }
+    >
+      {children}
+    </div>
+  );
+}

src/components/HighlightBlock/styles.module.css

@@ -0,0 +1,12 @@
+.light {
+  background: #fff3a0;        /* жёлтый фон */
+  padding: 16px;
+  border-radius: 8px;
+}
+
+.dark {
+  color: #ffe36b;             /* жёлтый текст */
+  background: transparent;    /* без подложки */
+  padding: 16px;
+  border-radius: 8px;
+}