762 lines
19 KiB
YAML
762 lines
19 KiB
YAML
swagger: "2.0"
|
||
info:
|
||
title: HY Room Service API
|
||
version: "1.0.0"
|
||
description: |
|
||
room-service 当前只暴露内部 gRPC + protobuf 接口，没有 HTTP JSON router。
|
||
本文件用 OpenAPI 2.0 记录 gRPC 合约，`paths` 使用 gRPC full method 作为文档路径，不代表真实 HTTP endpoint。
|
||
腾讯云 IM 房间系统消息是 room-service 的外发消息契约，记录在 definitions 中。
|
||
host: localhost:13001
|
||
basePath: /
|
||
schemes:
|
||
- http
|
||
consumes:
|
||
- application/grpc+proto
|
||
produces:
|
||
- application/grpc+proto
|
||
tags:
|
||
- name: room-command
|
||
description: RoomCommandService，改变房间状态的命令接口。
|
||
- name: room-guard
|
||
description: RoomGuardService，腾讯云 IM 入群和发言前的同步守卫。
|
||
- name: health
|
||
description: 标准 grpc.health.v1.Health。
|
||
responses:
|
||
GRPCError:
|
||
description: gRPC status error；稳定业务原因放在 google.rpc.ErrorInfo.reason。
|
||
schema:
|
||
$ref: "#/definitions/GRPCError"
|
||
paths:
|
||
/hyapp.room.v1.RoomCommandService/CreateRoom:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 创建房间
|
||
operationId: roomCreateRoom
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/CreateRoom
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/CreateRoomRequest"
|
||
responses:
|
||
"200":
|
||
description: 创建成功；CreateRoom 会确保腾讯云 IM 群组存在后再提交房间状态。
|
||
schema:
|
||
$ref: "#/definitions/CreateRoomResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/JoinRoom:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 加入房间业务 presence
|
||
operationId: roomJoinRoom
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/JoinRoom
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/JoinRoomRequest"
|
||
responses:
|
||
"200":
|
||
description: 加入成功；只维护 room-service presence，不创建腾讯云 IM 连接。
|
||
schema:
|
||
$ref: "#/definitions/JoinRoomResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/LeaveRoom:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 离开房间业务 presence
|
||
operationId: roomLeaveRoom
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/LeaveRoom
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/LeaveRoomRequest"
|
||
responses:
|
||
"200":
|
||
description: 离房成功；若用户在麦上会释放麦位。
|
||
schema:
|
||
$ref: "#/definitions/LeaveRoomResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/MicUp:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 上麦
|
||
operationId: roomMicUp
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MicUp
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/MicUpRequest"
|
||
responses:
|
||
"200":
|
||
description: 上麦成功。
|
||
schema:
|
||
$ref: "#/definitions/MicUpResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/MicDown:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 下麦
|
||
operationId: roomMicDown
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MicDown
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/MicDownRequest"
|
||
responses:
|
||
"200":
|
||
description: 下麦成功。
|
||
schema:
|
||
$ref: "#/definitions/MicDownResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/ChangeMicSeat:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 调整麦位
|
||
operationId: roomChangeMicSeat
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/ChangeMicSeat
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/ChangeMicSeatRequest"
|
||
responses:
|
||
"200":
|
||
description: 调整成功。
|
||
schema:
|
||
$ref: "#/definitions/ChangeMicSeatResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/MuteUser:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 设置房间内禁言
|
||
operationId: roomMuteUser
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MuteUser
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/MuteUserRequest"
|
||
responses:
|
||
"200":
|
||
description: 禁言状态修改成功；结果会影响 CheckSpeakPermission。
|
||
schema:
|
||
$ref: "#/definitions/MuteUserResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/KickUser:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 踢出房间用户
|
||
operationId: roomKickUser
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/KickUser
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/KickUserRequest"
|
||
responses:
|
||
"200":
|
||
description: 踢人成功；结果会影响 VerifyRoomPresence 和 CheckSpeakPermission。
|
||
schema:
|
||
$ref: "#/definitions/KickUserResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomCommandService/SendGift:
|
||
post:
|
||
tags:
|
||
- room-command
|
||
summary: 发送礼物
|
||
operationId: roomSendGift
|
||
x-grpc-full-method: /hyapp.room.v1.RoomCommandService/SendGift
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/SendGiftRequest"
|
||
responses:
|
||
"200":
|
||
description: 扣费成功并落入房间状态。
|
||
schema:
|
||
$ref: "#/definitions/SendGiftResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomGuardService/CheckSpeakPermission:
|
||
post:
|
||
tags:
|
||
- room-guard
|
||
summary: 发言前守卫
|
||
operationId: roomCheckSpeakPermission
|
||
x-grpc-full-method: /hyapp.room.v1.RoomGuardService/CheckSpeakPermission
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/CheckSpeakPermissionRequest"
|
||
responses:
|
||
"200":
|
||
description: 返回是否允许用户在房间发言。
|
||
schema:
|
||
$ref: "#/definitions/CheckSpeakPermissionResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/hyapp.room.v1.RoomGuardService/VerifyRoomPresence:
|
||
post:
|
||
tags:
|
||
- room-guard
|
||
summary: 入群前 presence 守卫
|
||
operationId: roomVerifyRoomPresence
|
||
x-grpc-full-method: /hyapp.room.v1.RoomGuardService/VerifyRoomPresence
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/VerifyRoomPresenceRequest"
|
||
responses:
|
||
"200":
|
||
description: 返回用户业务上是否仍在房间内。
|
||
schema:
|
||
$ref: "#/definitions/VerifyRoomPresenceResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/grpc.health.v1.Health/Check:
|
||
post:
|
||
tags:
|
||
- health
|
||
summary: 标准 gRPC health check
|
||
operationId: roomHealthCheck
|
||
x-grpc-full-method: /grpc.health.v1.Health/Check
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/HealthCheckRequest"
|
||
responses:
|
||
"200":
|
||
description: 返回 SERVING 或 NOT_SERVING；未知 service 返回 gRPC NotFound。
|
||
schema:
|
||
$ref: "#/definitions/HealthCheckResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
/grpc.health.v1.Health/Watch:
|
||
post:
|
||
tags:
|
||
- health
|
||
summary: 标准 gRPC health watch
|
||
operationId: roomHealthWatch
|
||
x-grpc-full-method: /grpc.health.v1.Health/Watch
|
||
x-server-streaming: true
|
||
parameters:
|
||
- name: body
|
||
in: body
|
||
required: true
|
||
schema:
|
||
$ref: "#/definitions/HealthCheckRequest"
|
||
responses:
|
||
"200":
|
||
description: 服务端流式推送健康状态变化。
|
||
schema:
|
||
$ref: "#/definitions/HealthCheckResponse"
|
||
default:
|
||
$ref: "#/responses/GRPCError"
|
||
definitions:
|
||
RequestMeta:
|
||
type: object
|
||
required:
|
||
- request_id
|
||
- command_id
|
||
- actor_user_id
|
||
- room_id
|
||
properties:
|
||
request_id:
|
||
type: string
|
||
command_id:
|
||
type: string
|
||
actor_user_id:
|
||
type: integer
|
||
format: int64
|
||
room_id:
|
||
type: string
|
||
pattern: "^[A-Za-z0-9_-]{1,48}$"
|
||
maxLength: 48
|
||
description: 命令所属房间 ID；CreateRoom 时必须兼容腾讯 IM GroupID 和 RTC strRoomId。
|
||
gateway_node_id:
|
||
type: string
|
||
session_id:
|
||
type: string
|
||
sent_at_ms:
|
||
type: integer
|
||
format: int64
|
||
CommandResult:
|
||
type: object
|
||
properties:
|
||
applied:
|
||
type: boolean
|
||
room_version:
|
||
type: integer
|
||
format: int64
|
||
server_time_ms:
|
||
type: integer
|
||
format: int64
|
||
RoomUser:
|
||
type: object
|
||
properties:
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
role:
|
||
type: string
|
||
joined_at_ms:
|
||
type: integer
|
||
format: int64
|
||
last_seen_at_ms:
|
||
type: integer
|
||
format: int64
|
||
SeatState:
|
||
type: object
|
||
properties:
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
locked:
|
||
type: boolean
|
||
RankItem:
|
||
type: object
|
||
properties:
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
score:
|
||
type: integer
|
||
format: int64
|
||
gift_value:
|
||
type: integer
|
||
format: int64
|
||
updated_at_ms:
|
||
type: integer
|
||
format: int64
|
||
RoomSnapshot:
|
||
type: object
|
||
properties:
|
||
room_id:
|
||
type: string
|
||
owner_user_id:
|
||
type: integer
|
||
format: int64
|
||
host_user_id:
|
||
type: integer
|
||
format: int64
|
||
mode:
|
||
type: string
|
||
status:
|
||
type: string
|
||
chat_enabled:
|
||
type: boolean
|
||
mic_seats:
|
||
type: array
|
||
items:
|
||
$ref: "#/definitions/SeatState"
|
||
online_users:
|
||
type: array
|
||
items:
|
||
$ref: "#/definitions/RoomUser"
|
||
admin_user_ids:
|
||
type: array
|
||
items:
|
||
type: integer
|
||
format: int64
|
||
ban_user_ids:
|
||
type: array
|
||
items:
|
||
type: integer
|
||
format: int64
|
||
mute_user_ids:
|
||
type: array
|
||
items:
|
||
type: integer
|
||
format: int64
|
||
gift_rank:
|
||
type: array
|
||
items:
|
||
$ref: "#/definitions/RankItem"
|
||
room_ext:
|
||
type: object
|
||
additionalProperties:
|
||
type: string
|
||
heat:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
format: int64
|
||
CreateRoomRequest:
|
||
type: object
|
||
required:
|
||
- meta
|
||
- seat_count
|
||
- mode
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
owner_user_id:
|
||
type: integer
|
||
format: int64
|
||
description: 内部 gRPC 字段；缺省时 room-service 使用 `meta.actor_user_id` 作为 owner。外部 gateway HTTP 不接收该字段。
|
||
host_user_id:
|
||
type: integer
|
||
format: int64
|
||
description: 内部 gRPC 字段；缺省时 room-service 使用 owner 作为默认 host。外部 gateway HTTP 不接收该字段。
|
||
seat_count:
|
||
type: integer
|
||
format: int32
|
||
minimum: 1
|
||
description: 麦位数量，必须大于 0。
|
||
mode:
|
||
type: string
|
||
minLength: 1
|
||
description: 房间模式，不能为空；当前 room-service 保存并通过快照透出。
|
||
CreateRoomResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
JoinRoomRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
role:
|
||
type: string
|
||
JoinRoomResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
user:
|
||
$ref: "#/definitions/RoomUser"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
LeaveRoomRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
LeaveRoomResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
MicUpRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
MicUpResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
MicDownRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
MicDownResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
ChangeMicSeatRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
ChangeMicSeatResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
MuteUserRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
muted:
|
||
type: boolean
|
||
MuteUserResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
KickUserRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
KickUserResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
SendGiftRequest:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: "#/definitions/RequestMeta"
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
gift_id:
|
||
type: string
|
||
gift_count:
|
||
type: integer
|
||
format: int32
|
||
gift_unit_value:
|
||
type: integer
|
||
format: int64
|
||
SendGiftResponse:
|
||
type: object
|
||
properties:
|
||
result:
|
||
$ref: "#/definitions/CommandResult"
|
||
billing_receipt_id:
|
||
type: string
|
||
room_heat:
|
||
type: integer
|
||
format: int64
|
||
gift_rank:
|
||
type: array
|
||
items:
|
||
$ref: "#/definitions/RankItem"
|
||
room:
|
||
$ref: "#/definitions/RoomSnapshot"
|
||
CheckSpeakPermissionRequest:
|
||
type: object
|
||
properties:
|
||
room_id:
|
||
type: string
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
CheckSpeakPermissionResponse:
|
||
type: object
|
||
properties:
|
||
allowed:
|
||
type: boolean
|
||
reason:
|
||
type: string
|
||
enum:
|
||
- room_not_found
|
||
- not_in_room
|
||
- user_banned
|
||
- user_muted
|
||
- chat_disabled
|
||
room_version:
|
||
type: integer
|
||
format: int64
|
||
VerifyRoomPresenceRequest:
|
||
type: object
|
||
properties:
|
||
room_id:
|
||
type: string
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
session_id:
|
||
type: string
|
||
VerifyRoomPresenceResponse:
|
||
type: object
|
||
properties:
|
||
present:
|
||
type: boolean
|
||
reason:
|
||
type: string
|
||
enum:
|
||
- room_not_found
|
||
- not_in_room
|
||
- user_banned
|
||
room_version:
|
||
type: integer
|
||
format: int64
|
||
RoomSystemMessage:
|
||
type: object
|
||
properties:
|
||
event_id:
|
||
type: string
|
||
room_id:
|
||
type: string
|
||
event_type:
|
||
type: string
|
||
enum:
|
||
- room_created
|
||
- room_user_joined
|
||
- room_user_left
|
||
- room_mic_changed
|
||
- room_user_muted
|
||
- room_user_kicked
|
||
- room_gift_sent
|
||
- room_heat_changed
|
||
- room_rank_changed
|
||
actor_user_id:
|
||
type: integer
|
||
format: int64
|
||
target_user_id:
|
||
type: integer
|
||
format: int64
|
||
seat_no:
|
||
type: integer
|
||
format: int32
|
||
gift_value:
|
||
type: integer
|
||
format: int64
|
||
room_heat:
|
||
type: integer
|
||
format: int64
|
||
room_version:
|
||
type: integer
|
||
format: int64
|
||
text:
|
||
type: string
|
||
attributes:
|
||
type: object
|
||
additionalProperties:
|
||
type: string
|
||
description: room-service 发送到腾讯云 IM 的 `TIMCustomElem.Data` 和 `CloudCustomData` 稳定载荷。
|
||
TencentTIMCustomElem:
|
||
type: object
|
||
properties:
|
||
MsgType:
|
||
type: string
|
||
enum:
|
||
- TIMCustomElem
|
||
MsgContent:
|
||
type: object
|
||
properties:
|
||
Data:
|
||
$ref: "#/definitions/RoomSystemMessage"
|
||
Desc:
|
||
type: string
|
||
description: 与 `RoomSystemMessage.event_type` 一致。
|
||
Ext:
|
||
type: string
|
||
enum:
|
||
- room_system_message
|
||
Sound:
|
||
type: string
|
||
description: 腾讯云 IM 群系统消息元素结构。
|
||
HealthCheckRequest:
|
||
type: object
|
||
properties:
|
||
service:
|
||
type: string
|
||
description: 空字符串或 `room-service`。
|
||
HealthCheckResponse:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: integer
|
||
format: int32
|
||
enum:
|
||
- 0
|
||
- 1
|
||
- 2
|
||
- 3
|
||
x-enum-names:
|
||
- UNKNOWN
|
||
- SERVING
|
||
- NOT_SERVING
|
||
- SERVICE_UNKNOWN
|
||
GRPCError:
|
||
type: object
|
||
properties:
|
||
grpc_code:
|
||
type: string
|
||
enum:
|
||
- InvalidArgument
|
||
- NotFound
|
||
- FailedPrecondition
|
||
- Unauthenticated
|
||
- PermissionDenied
|
||
- Unavailable
|
||
- AlreadyExists
|
||
- Internal
|
||
- Aborted
|
||
reason:
|
||
type: string
|
||
message:
|
||
type: string
|
||
error_info_domain:
|
||
type: string
|
||
enum:
|
||
- hyapp
|