292 lines
13 KiB
JSON
292 lines
13 KiB
JSON
{
|
|
"paths": {
|
|
"/calendars": {
|
|
"get": {
|
|
"tags": ["Calendars"],
|
|
"summary": "List calendars",
|
|
"description": "Returns all calendars the user owns or has been shared with. Each calendar includes the user's role (owner, editor, or viewer). Requires `calendars:read` scope.",
|
|
"operationId": "listCalendars",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of calendars",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "page"],
|
|
"properties": {
|
|
"items": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } },
|
|
"page": { "$ref": "#/components/schemas/PageInfo" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Create a calendar",
|
|
"description": "Creates a new calendar owned by the authenticated user. Requires `calendars:write` scope.",
|
|
"operationId": "createCalendar",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["name"],
|
|
"properties": {
|
|
"name": { "type": "string", "minLength": 1, "maxLength": 80, "example": "Work" },
|
|
"color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#22C55E" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Calendar created",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["calendar"],
|
|
"properties": {
|
|
"calendar": { "$ref": "#/components/schemas/Calendar" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
}
|
|
},
|
|
"/calendars/{id}": {
|
|
"get": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Get a calendar",
|
|
"description": "Returns a single calendar by ID. User must be owner or member. Requires `calendars:read` scope.",
|
|
"operationId": "getCalendar",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Calendar details",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["calendar"],
|
|
"properties": {
|
|
"calendar": { "$ref": "#/components/schemas/Calendar" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
},
|
|
"put": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Update a calendar",
|
|
"description": "Updates a calendar's name, color, or public status. Only the owner can change `is_public`. Requires `calendars:write` scope.",
|
|
"operationId": "updateCalendar",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": { "type": "string", "minLength": 1, "maxLength": 80, "example": "Work Calendar" },
|
|
"color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#22C55E" },
|
|
"is_public": { "type": "boolean" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Calendar updated",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["calendar"],
|
|
"properties": {
|
|
"calendar": { "$ref": "#/components/schemas/Calendar" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Delete a calendar",
|
|
"description": "Soft-deletes a calendar and all its events. Only the owner can delete. Requires `calendars:write` scope.",
|
|
"operationId": "deleteCalendar",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Calendar deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Only owner can delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
}
|
|
},
|
|
"/calendars/{id}/share": {
|
|
"post": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Share a calendar",
|
|
"description": "Shares a calendar with another user by email, granting them a role (editor or viewer). Only the owner can share. Cannot share with self. Requires `calendars:write` scope.",
|
|
"operationId": "shareCalendar",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["target", "role"],
|
|
"properties": {
|
|
"target": {
|
|
"type": "object",
|
|
"required": ["email"],
|
|
"properties": {
|
|
"email": { "type": "string", "format": "email", "example": "other@example.com" }
|
|
}
|
|
},
|
|
"role": { "type": "string", "enum": ["editor", "viewer"], "example": "editor" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": { "description": "Calendar shared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
|
|
"400": { "description": "Validation error (e.g. sharing with self)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Only owner can share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar or target user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
}
|
|
},
|
|
"/calendars/{id}/members": {
|
|
"get": {
|
|
"tags": ["Calendars"],
|
|
"summary": "List calendar members",
|
|
"description": "Returns all members of a calendar with their roles. Requires `calendars:read` scope.",
|
|
"operationId": "listCalendarMembers",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of members",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "page"],
|
|
"properties": {
|
|
"items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarMember" } },
|
|
"page": { "$ref": "#/components/schemas/PageInfo" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
}
|
|
},
|
|
"/calendars/{id}/members/{userID}": {
|
|
"delete": {
|
|
"tags": ["Calendars"],
|
|
"summary": "Remove a calendar member",
|
|
"description": "Removes a member from a shared calendar. Only the owner can remove members. The owner cannot be removed. Requires `calendars:write` scope.",
|
|
"operationId": "removeCalendarMember",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "Calendar ID"
|
|
},
|
|
{
|
|
"name": "userID",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string", "format": "uuid" },
|
|
"description": "User ID of the member to remove"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Member removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
|
|
"400": { "description": "Cannot remove owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"403": { "description": "Only owner can remove members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
|
"404": { "description": "Calendar or member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|