276 lines
13 KiB
Python
276 lines
13 KiB
Python
# Copyright (c) 2023-present Plane Software, Inc. and contributors
|
|
# SPDX-License-Identifier: AGPL-3.0-only
|
|
# See the LICENSE file for details.
|
|
|
|
"""
|
|
OpenAPI/Swagger configuration for drf-spectacular.
|
|
|
|
This file contains the complete configuration for API documentation generation.
|
|
"""
|
|
|
|
SPECTACULAR_SETTINGS = {
|
|
# ========================================================================
|
|
# Basic API Information
|
|
# ========================================================================
|
|
"TITLE": "The Plane REST API",
|
|
"DESCRIPTION": (
|
|
"The Plane REST API\n\n"
|
|
"Visit our quick start guide and full API documentation at "
|
|
"[developers.plane.so](https://developers.plane.so/api-reference/introduction)."
|
|
),
|
|
"CONTACT": {
|
|
"name": "Plane",
|
|
"url": "https://plane.so",
|
|
"email": "support@plane.so",
|
|
},
|
|
"VERSION": "0.0.1",
|
|
"LICENSE": {
|
|
"name": "GNU AGPLv3",
|
|
"url": "https://github.com/makeplane/plane/blob/preview/LICENSE.txt",
|
|
},
|
|
# ========================================================================
|
|
# Schema Generation Settings
|
|
# ========================================================================
|
|
"SERVE_INCLUDE_SCHEMA": False,
|
|
"SCHEMA_PATH_PREFIX": "/api/v1/",
|
|
"SCHEMA_CACHE_TIMEOUT": 0, # disables caching
|
|
# ========================================================================
|
|
# Processing Hooks
|
|
# ========================================================================
|
|
"PREPROCESSING_HOOKS": [
|
|
"plane.utils.openapi.hooks.preprocess_filter_api_v1_paths",
|
|
],
|
|
# ========================================================================
|
|
# Server Configuration
|
|
# ========================================================================
|
|
"SERVERS": [
|
|
{"url": "http://localhost:8000", "description": "Local"},
|
|
{"url": "https://api.plane.so", "description": "Production"},
|
|
],
|
|
# ========================================================================
|
|
# API Tag Definitions
|
|
# ========================================================================
|
|
"TAGS": [
|
|
# System Features
|
|
{
|
|
"name": "Assets",
|
|
"description": (
|
|
"**File Upload & Presigned URLs**\n\n"
|
|
"Generate presigned URLs for direct file uploads to cloud storage. Handle user avatars, "
|
|
"cover images, and generic project assets with secure upload workflows.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Generate presigned URLs for S3 uploads\n"
|
|
"- Support for user avatars and cover images\n"
|
|
"- Generic asset upload for projects\n"
|
|
"- File validation and size limits\n\n"
|
|
"*Use Cases:* User profile images, project file uploads, secure direct-to-cloud uploads."
|
|
),
|
|
},
|
|
# Project Organization
|
|
{
|
|
"name": "Cycles",
|
|
"description": (
|
|
"**Sprint & Development Cycles**\n\n"
|
|
"Create and manage development cycles (sprints) to organize work into time-boxed iterations. "
|
|
"Track progress, assign work items, and monitor team velocity.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create and configure development cycles\n"
|
|
"- Assign work items to cycles\n"
|
|
"- Track cycle progress and completion\n"
|
|
"- Generate cycle analytics and reports\n\n"
|
|
"*Use Cases:* Sprint planning, iterative development, progress tracking, team velocity."
|
|
),
|
|
},
|
|
# System Features
|
|
{
|
|
"name": "Intake",
|
|
"description": (
|
|
"**Work Item Intake Queue**\n\n"
|
|
"Manage incoming work items through a dedicated intake queue for triage and review. "
|
|
"Submit, update, and process work items before they enter the main project workflow.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Submit work items to intake queue\n"
|
|
"- Review and triage incoming work items\n"
|
|
"- Update intake work item status and properties\n"
|
|
"- Accept, reject, or modify work items before approval\n\n"
|
|
"*Use Cases:* Work item triage, external submissions, quality review, approval workflows."
|
|
),
|
|
},
|
|
# Project Organization
|
|
{
|
|
"name": "Labels",
|
|
"description": (
|
|
"**Labels & Tags**\n\n"
|
|
"Create and manage labels to categorize and organize work items. Use color-coded labels "
|
|
"for easy identification, filtering, and project organization.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create custom labels with colors and descriptions\n"
|
|
"- Apply labels to work items for categorization\n"
|
|
"- Filter and search by labels\n"
|
|
"- Organize labels across projects\n\n"
|
|
"*Use Cases:* Priority marking, feature categorization, bug classification, team organization."
|
|
),
|
|
},
|
|
# Team & User Management
|
|
{
|
|
"name": "Members",
|
|
"description": (
|
|
"**Team Member Management**\n\n"
|
|
"Manage team members, roles, and permissions within projects and workspaces. "
|
|
"Control access levels and track member participation.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Invite and manage team members\n"
|
|
"- Assign roles and permissions\n"
|
|
"- Control project and workspace access\n"
|
|
"- Track member activity and participation\n\n"
|
|
"*Use Cases:* Team setup, access control, role management, collaboration."
|
|
),
|
|
},
|
|
# Project Organization
|
|
{
|
|
"name": "Modules",
|
|
"description": (
|
|
"**Feature Modules**\n\n"
|
|
"Group related work items into modules for better organization and tracking. "
|
|
"Plan features, track progress, and manage deliverables at a higher level.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create and organize feature modules\n"
|
|
"- Group work items by module\n"
|
|
"- Track module progress and completion\n"
|
|
"- Manage module leads and assignments\n\n"
|
|
"*Use Cases:* Feature planning, release organization, progress tracking, team coordination."
|
|
),
|
|
},
|
|
# Core Project Management
|
|
{
|
|
"name": "Projects",
|
|
"description": (
|
|
"**Project Management**\n\n"
|
|
"Create and manage projects to organize your development work. Configure project settings, "
|
|
"manage team access, and control project visibility.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create, update, and delete projects\n"
|
|
"- Configure project settings and preferences\n"
|
|
"- Manage team access and permissions\n"
|
|
"- Control project visibility and sharing\n\n"
|
|
"*Use Cases:* Project setup, team collaboration, access control, project configuration."
|
|
),
|
|
},
|
|
# Project Organization
|
|
{
|
|
"name": "States",
|
|
"description": (
|
|
"**Workflow States**\n\n"
|
|
"Define custom workflow states for work items to match your team's process. "
|
|
"Configure state transitions and track work item progress through different stages.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create custom workflow states\n"
|
|
"- Configure state transitions and rules\n"
|
|
"- Track work item progress through states\n"
|
|
"- Set state-based permissions and automation\n\n"
|
|
"*Use Cases:* Custom workflows, status tracking, process automation, progress monitoring."
|
|
),
|
|
},
|
|
# Team & User Management
|
|
{
|
|
"name": "Users",
|
|
"description": (
|
|
"**Current User Information**\n\n"
|
|
"Get information about the currently authenticated user including profile details "
|
|
"and account settings.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Retrieve current user profile\n"
|
|
"- Access user account information\n"
|
|
"- View user preferences and settings\n"
|
|
"- Get authentication context\n\n"
|
|
"*Use Cases:* Profile display, user context, account information, authentication status."
|
|
),
|
|
},
|
|
# Work Item Management
|
|
{
|
|
"name": "Work Item Activity",
|
|
"description": (
|
|
"**Activity History & Search**\n\n"
|
|
"View activity history and search for work items across the workspace. "
|
|
"Get detailed activity logs and find work items using text search.\n\n"
|
|
"*Key Features:*\n"
|
|
"- View work item activity history\n"
|
|
"- Search work items across workspace\n"
|
|
"- Track changes and modifications\n"
|
|
"- Filter search results by project\n\n"
|
|
"*Use Cases:* Activity tracking, work item discovery, change history, workspace search."
|
|
),
|
|
},
|
|
{
|
|
"name": "Work Item Attachments",
|
|
"description": (
|
|
"**Work Item File Attachments**\n\n"
|
|
"Generate presigned URLs for uploading files directly to specific work items. "
|
|
"Upload and manage attachments associated with work items.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Generate presigned URLs for work item attachments\n"
|
|
"- Upload files directly to work items\n"
|
|
"- Retrieve and manage attachment metadata\n"
|
|
"- Delete attachments from work items\n\n"
|
|
"*Use Cases:* Screenshots, error logs, design files, supporting documents."
|
|
),
|
|
},
|
|
{
|
|
"name": "Work Item Comments",
|
|
"description": (
|
|
"**Comments & Discussions**\n\n"
|
|
"Add comments and discussions to work items for team collaboration. "
|
|
"Support threaded conversations, mentions, and rich text formatting.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Add comments to work items\n"
|
|
"- Thread conversations and replies\n"
|
|
"- Mention users and trigger notifications\n"
|
|
"- Rich text and markdown support\n\n"
|
|
"*Use Cases:* Team discussions, progress updates, code reviews, decision tracking."
|
|
),
|
|
},
|
|
{
|
|
"name": "Work Item Links",
|
|
"description": (
|
|
"**External Links & References**\n\n"
|
|
"Link work items to external resources like documentation, repositories, or design files. "
|
|
"Maintain connections between work items and external systems.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Add external URL links to work items\n"
|
|
"- Validate and preview linked resources\n"
|
|
"- Organize links by type and category\n"
|
|
"- Track link usage and access\n\n"
|
|
"*Use Cases:* Documentation links, repository connections, design references, external tools."
|
|
),
|
|
},
|
|
{
|
|
"name": "Work Items",
|
|
"description": (
|
|
"**Work Items & Tasks**\n\n"
|
|
"Create and manage work items like tasks, bugs, features, and user stories. "
|
|
"The core entities for tracking work in your projects.\n\n"
|
|
"*Key Features:*\n"
|
|
"- Create, update, and manage work items\n"
|
|
"- Assign to team members and set priorities\n"
|
|
"- Track progress through workflow states\n"
|
|
"- Set due dates, estimates, and relationships\n\n"
|
|
"*Use Cases:* Bug tracking, task management, feature development, sprint planning."
|
|
),
|
|
},
|
|
],
|
|
# ========================================================================
|
|
# Security & Authentication
|
|
# ========================================================================
|
|
"AUTHENTICATION_WHITELIST": [
|
|
"plane.api.middleware.api_authentication.APIKeyAuthentication",
|
|
],
|
|
# ========================================================================
|
|
# Schema Generation Options
|
|
# ========================================================================
|
|
"COMPONENT_NO_READ_ONLY_REQUIRED": True,
|
|
"COMPONENT_SPLIT_REQUEST": True,
|
|
"ENUM_NAME_OVERRIDES": {
|
|
"ModuleStatusEnum": "plane.db.models.module.ModuleStatus",
|
|
"IntakeWorkItemStatusEnum": "plane.db.models.intake.IntakeIssueStatus",
|
|
},
|
|
}
|