Enhance API endpoints with response type annotations
CI / Backend (build + test) (push) Successful in 1m15s
CI / Frontend (lint + typecheck + build) (push) Successful in 30s

- Updated various API endpoints to include response type annotations using .Produces<T>() for better documentation and type safety.
- Enhanced activation, admin, user, config, and other endpoints to specify response types, improving clarity for frontend integration.
- Added new DTOs for structured responses in authentication and Telegram-related endpoints.
- Improved overall API schema generation to reflect these changes, ensuring consistency between backend and frontend types.
This commit is contained in:
Leonid Pershin
2026-07-02 12:56:03 +03:00
parent 8067be3c35
commit 8b92204733
15 changed files with 493 additions and 143 deletions
+391 -66
View File
@@ -24,6 +24,15 @@ export interface paths {
responses: {
/** @description OK */
200: {
headers: {
[name: string]: unknown;
};
content: {
"text/plain": string;
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
@@ -60,7 +69,11 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": {
[key: string]: components["schemas"]["ClientAppDto"][];
};
};
};
};
};
@@ -99,7 +112,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["RegisterResult"];
};
};
};
};
@@ -136,7 +151,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AuthResponseDto"];
};
};
};
};
@@ -169,7 +186,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AuthResponseDto"];
};
};
};
};
@@ -197,8 +216,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -234,8 +253,8 @@ export interface paths {
};
};
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -270,7 +289,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["CurrentUserDto"];
};
};
};
};
@@ -285,8 +306,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -320,7 +341,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["ActivationStatusDto"];
};
};
};
};
@@ -359,7 +382,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["ActivationRequestDto"];
};
};
};
};
@@ -394,7 +419,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["PagedListOfActivationRequestAdminDto"];
};
};
};
};
@@ -426,8 +453,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -465,8 +492,8 @@ export interface paths {
};
};
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -501,7 +528,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["RoleDto"][];
};
};
};
};
@@ -524,7 +553,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["RoleDto"];
};
};
};
};
@@ -562,7 +593,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["RoleDto"];
};
};
};
};
@@ -578,8 +611,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -620,8 +653,8 @@ export interface paths {
};
};
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -652,7 +685,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["NodeDto"][];
};
};
};
};
@@ -675,7 +710,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["NodeDto"];
};
};
};
};
@@ -713,7 +750,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["NodeDto"];
};
};
};
};
@@ -729,8 +768,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -768,7 +807,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["SyncNodeResultDto"];
};
};
};
};
@@ -803,7 +844,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["NodeProbeResultDto"];
};
};
};
};
@@ -836,7 +879,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["InboundDto"][];
};
};
};
};
@@ -876,7 +921,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["InboundDto"];
};
};
};
};
@@ -908,7 +955,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AvailableInboundDto"][];
};
};
};
};
@@ -941,7 +990,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["GetMyConfigsResult"];
};
};
};
};
@@ -964,7 +1015,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["VpnConfigDto"];
};
};
};
};
@@ -995,8 +1048,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1026,7 +1079,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["VpnConfigDto"];
};
};
};
};
@@ -1057,7 +1112,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["VpnConfigDto"];
};
};
};
};
@@ -1090,7 +1147,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["ConfigLinkResponseDto"];
};
};
};
};
@@ -1123,7 +1182,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["MySubscriptionResponseDto"];
};
};
};
};
@@ -1160,7 +1221,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["PagedListOfUserSummaryDto"];
};
};
};
};
@@ -1196,8 +1259,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1231,8 +1294,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1266,8 +1329,8 @@ export interface paths {
};
};
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1304,7 +1367,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["VpnConfigDto"][];
};
};
};
};
@@ -1337,8 +1402,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1372,7 +1437,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["StatsDto"];
};
};
};
};
@@ -1408,7 +1475,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["PagedListOfAuditLogDto"];
};
};
};
};
@@ -1441,7 +1510,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AdminAppDto"][];
};
};
};
};
@@ -1464,7 +1535,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AdminAppDto"];
};
};
};
};
@@ -1502,7 +1575,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["AdminAppDto"];
};
};
};
};
@@ -1518,8 +1593,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1555,7 +1630,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["LinkTokenResponseDto"];
};
};
};
};
@@ -1583,8 +1660,8 @@ export interface paths {
};
requestBody?: never;
responses: {
/** @description OK */
200: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
@@ -1621,7 +1698,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["TelegramLoginRequestResponseDto"];
};
};
};
};
@@ -1654,7 +1733,9 @@ export interface paths {
headers: {
[name: string]: unknown;
};
content?: never;
content: {
"application/json": components["schemas"]["TelegramLoginStatusResponseDto"];
};
};
};
};
@@ -1670,8 +1751,69 @@ export interface paths {
export type webhooks = Record<string, never>;
export interface components {
schemas: {
ActivationRequestAdminDto: {
/** Format: uuid */
id: string;
/** Format: uuid */
userId: string;
userName: string;
comment: null | string;
status: components["schemas"]["ActivationStatus"];
/** Format: date-time */
createdAt: string;
};
ActivationRequestDto: {
/** Format: uuid */
id: string;
comment: null | string;
/** Format: date-time */
createdAt: string;
};
/** @enum {unknown} */
ActivationStatus: "Pending" | "Approved" | "Rejected" | null;
ActivationStatus: "Pending" | "Approved" | "Rejected";
ActivationStatusDto: {
isActivated: boolean;
pendingRequest: null | components["schemas"]["ActivationRequestDto"];
};
AdminAppDto: {
/** Format: uuid */
id: string;
name: string;
downloadUrl: string;
operatingSystem: components["schemas"]["OsPlatform"];
description: null | string;
iconUrl: null | string;
/** Format: int32 */
sortOrder: number | string;
isEnabled: boolean;
};
AuditLogDto: {
/** Format: int64 */
id: number | string;
/** Format: uuid */
actorId: null | string;
action: string;
targetType: string;
targetId: string;
metadata: null | string;
source: components["schemas"]["AuditSource"];
/** Format: date-time */
createdAt: string;
};
/** @enum {unknown} */
AuditSource: "Web" | "Telegram" | "System";
AuthResponseDto: {
accessToken: string;
/** Format: date-time */
expiresAt: string;
user: components["schemas"]["CurrentUserDto"];
};
AvailableInboundDto: {
/** Format: uuid */
inboundId: string;
displayName: string;
protocol: components["schemas"]["VpnProtocol"];
};
ChangePasswordCommand: {
currentPassword: string;
newPassword: string;
@@ -1680,6 +1822,20 @@ export interface components {
/** Format: uuid */
roleId: string;
};
ClientAppDto: {
/** Format: uuid */
id: string;
name: string;
downloadUrl: string;
description: null | string;
iconUrl: null | string;
};
ConfigLinkResponseDto: {
connectionString: string;
subscriptionUrl: string;
};
/** @enum {unknown} */
ConfigStatus: "Active" | "Disabled" | "Expired" | "LimitReached" | "Revoked";
CreateAppCommand: {
name: string;
downloadUrl: string;
@@ -1701,17 +1857,102 @@ export interface components {
/** Format: int32 */
maxConfigs: number | string;
};
CurrentUserDto: {
/** Format: uuid */
id: string;
userName: string;
role: string;
isActivated: boolean;
telegramLinked: boolean;
};
EditConfigBody: {
label: null | string;
/** Format: int32 */
deviceLimit: null | number | string;
};
GetMyConfigsResult: {
configs: components["schemas"]["VpnConfigDto"][];
/** Format: int32 */
maxConfigs: number | string;
};
InboundDto: {
/** Format: uuid */
id: string;
/** Format: uuid */
nodeId: string;
remoteInboundId: string;
protocol: components["schemas"]["VpnProtocol"];
remark: string;
/** Format: int32 */
port: number | string;
isPublished: boolean;
displayName: null | string;
/** Format: int32 */
maxClients: null | number | string;
allowedRoleIds: string[];
/** Format: date-time */
lastSyncAt: null | string;
};
LinkTokenResponseDto: {
deepLink: null | string;
/** Format: date-time */
expiresAt: string;
};
LoginCommand: {
userName: string;
password: string;
};
MySubscriptionResponseDto: {
subscriptionUrl: string;
};
NodeDto: {
/** Format: uuid */
id: string;
name: string;
baseAddress: string;
username: string;
location: null | string;
status: components["schemas"]["NodeStatus"];
isEnabled: boolean;
/** Format: date-time */
lastSyncAt: null | string;
};
NodeProbeResultDto: {
isReachable: boolean;
errorMessage: null | string;
status: components["schemas"]["NodeStatus"];
};
/** @enum {unknown} */
NodeStatus: "Unknown" | "Online" | "Offline";
/** @enum {unknown} */
OsPlatform: "IOS" | "Android" | "Windows" | "MacOS" | "Linux";
PagedListOfActivationRequestAdminDto: {
items: components["schemas"]["ActivationRequestAdminDto"][];
/** Format: int32 */
total: number | string;
/** Format: int32 */
page: number | string;
/** Format: int32 */
pageSize: number | string;
};
PagedListOfAuditLogDto: {
items: components["schemas"]["AuditLogDto"][];
/** Format: int32 */
total: number | string;
/** Format: int32 */
page: number | string;
/** Format: int32 */
pageSize: number | string;
};
PagedListOfUserSummaryDto: {
items: components["schemas"]["UserSummaryDto"][];
/** Format: int32 */
total: number | string;
/** Format: int32 */
page: number | string;
/** Format: int32 */
pageSize: number | string;
};
PublishInboundBody: {
isPublished: boolean;
displayName: null | string;
@@ -1730,6 +1971,11 @@ export interface components {
password: string;
location: null | string;
};
RegisterResult: {
/** Format: uuid */
id: string;
userName: string;
};
RejectActivationBody: {
reason: null | string;
};
@@ -1739,6 +1985,55 @@ export interface components {
ResetPasswordBody: {
newPassword: string;
};
RoleDto: {
/** Format: uuid */
id: string;
name: string;
/** Format: int32 */
maxConfigs: number | string;
isSystem: boolean;
};
StatsDto: {
/** Format: int32 */
totalUsers: number | string;
/** Format: int32 */
activatedUsers: number | string;
/** Format: int32 */
pendingActivationRequests: number | string;
/** Format: int32 */
totalNodes: number | string;
/** Format: int32 */
onlineNodes: number | string;
/** Format: int32 */
totalConfigs: number | string;
/** Format: int32 */
activeConfigs: number | string;
/** Format: int64 */
totalUsedUpBytes: number | string;
/** Format: int64 */
totalUsedDownBytes: number | string;
};
SyncNodeResultDto: {
/** Format: int32 */
inboundsSynced: number | string;
status: components["schemas"]["NodeStatus"];
};
TelegramLoginRequestResponseDto: {
/** Format: uuid */
requestId: string;
deepLink: null | string;
/** Format: date-time */
expiresAt: string;
};
/** @enum {unknown} */
TelegramLoginStatus: "Pending" | "Approved" | "Rejected" | "Expired" | "Consumed";
TelegramLoginStatusResponseDto: {
status: components["schemas"]["TelegramLoginStatus"];
accessToken: null | string;
/** Format: date-time */
expiresAt: null | string;
user: null | components["schemas"]["CurrentUserDto"];
};
UpdateAppBody: {
name: string;
downloadUrl: string;
@@ -1760,6 +2055,36 @@ export interface components {
/** Format: int32 */
maxConfigs: number | string;
};
UserSummaryDto: {
/** Format: uuid */
id: string;
userName: string;
role: string;
isActivated: boolean;
isBlocked: boolean;
/** Format: date-time */
activatedAt: null | string;
};
VpnConfigDto: {
/** Format: uuid */
id: string;
label: null | string;
protocol: components["schemas"]["VpnProtocol"];
location: string;
/** Format: int32 */
deviceLimit: number | string;
/** Format: int64 */
usedUpBytes: number | string;
/** Format: int64 */
usedDownBytes: number | string;
/** Format: date-time */
expiresAt: null | string;
status: components["schemas"]["ConfigStatus"];
/** Format: date-time */
createdAt: string;
};
/** @enum {unknown} */
VpnProtocol: "Vless" | "Vmess" | "Trojan" | "Shadowsocks";
};
responses: never;
parameters: never;
+3 -2
View File
@@ -1,6 +1,7 @@
// Типы вручную синхронизированы с DTO бэкенда (см. backend/src/PnvPanel.Application/**).
// TODO: заменить на `pnpm gen:api` (openapi-typescript), когда бэкенд доступен по сети
// (сейчас недоступен локально — Postgres/Docker не подняты, схему /openapi/v1.json взять негде).
// Держи в синхроне с `pnpm gen:api` (openapi-typescript, -> schema.gen.ts): все эндпоинты аннотированы
// `.Produces<T>()`, схема полностью описывает тела ответов — сверяй при расхождении вручную (сгенерированный
// файл не используется напрямую фичами — предпочтены осмысленные имена и generic PagedList<T>, которых нет в JSON Schema).
export type ApiError = {
title: string