SILVER/NODEDC_TASKMANAGER
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

base

Browse Source
This commit is contained in:
DCCONSTRUCTIONS
2026-04-18 18:39:25 +03:00
commit 3ba092b60c
4944 changed files with 497564 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plane-src/apps/api/plane/utils/openapi/README.md
+102
View File
@@ -0,0 +1,102 @@
# OpenAPI Utilities Module
This module provides a well-organized structure for OpenAPI/drf-spectacular utilities, replacing the monolithic `openapi_spec_helpers.py` file with a more maintainable modular approach.
## Structure
```
plane/utils/openapi/
├── __init__.py # Main module that re-exports everything
├── auth.py # Authentication extensions
├── parameters.py # Common OpenAPI parameters
├── responses.py # Common OpenAPI responses
├── examples.py # Common OpenAPI examples
├── decorators.py # Helper decorators for different endpoint types
└── hooks.py # Schema processing hooks (pre/post processing)
```
## Usage
### Import Everything (Recommended for backwards compatibility)
```python
from plane.utils.openapi import (
asset_docs,
ASSET_ID_PARAMETER,
UNAUTHORIZED_RESPONSE,
# ... other imports
)
```
### Import from Specific Modules (Recommended for new code)
```python
from plane.utils.openapi.decorators import asset_docs
from plane.utils.openapi.parameters import ASSET_ID_PARAMETER
from plane.utils.openapi.responses import UNAUTHORIZED_RESPONSE
```
## Module Contents
### auth.py
- `APIKeyAuthenticationExtension` - X-API-Key authentication
- `APITokenAuthenticationExtension` - Bearer token authentication
### parameters.py
- Path parameters: `WORKSPACE_SLUG_PARAMETER`, `PROJECT_ID_PARAMETER`, `ISSUE_ID_PARAMETER`, `ASSET_ID_PARAMETER`
- Query parameters: `CURSOR_PARAMETER`, `PER_PAGE_PARAMETER`
### responses.py
- Auth responses: `UNAUTHORIZED_RESPONSE`, `FORBIDDEN_RESPONSE`
- Resource responses: `NOT_FOUND_RESPONSE`, `VALIDATION_ERROR_RESPONSE`
- Asset responses: `PRESIGNED_URL_SUCCESS_RESPONSE`, `ASSET_UPDATED_RESPONSE`, etc.
- Generic asset responses: `GENERIC_ASSET_UPLOAD_SUCCESS_RESPONSE`, `ASSET_DOWNLOAD_SUCCESS_RESPONSE`, etc.
### examples.py
- `FILE_UPLOAD_EXAMPLE`, `WORKSPACE_EXAMPLE`, `PROJECT_EXAMPLE`, `ISSUE_EXAMPLE`
### decorators.py
- `workspace_docs()` - For workspace endpoints
- `project_docs()` - For project endpoints
- `issue_docs()` - For issue/work item endpoints
- `asset_docs()` - For asset endpoints
### hooks.py
- `preprocess_filter_api_v1_paths()` - Filters API v1 paths
- `postprocess_assign_tags()` - Assigns tags based on URL patterns
- `generate_operation_summary()` - Generates operation summaries
## Migration Status
✅ **FULLY COMPLETE** - All components from the legacy `openapi_spec_helpers.py` have been successfully migrated to this modular structure and the old file has been completely removed. All imports have been updated to use the new modular structure.
### What was migrated:
- ✅ All authentication extensions
- ✅ All common parameters and responses
- ✅ All helper decorators
- ✅ All schema processing hooks
- ✅ All examples and reusable components
- ✅ All asset view decorators converted to use new helpers
- ✅ All view imports updated to new module paths
- ✅ Legacy file completely removed
### Files updated:
- `plane/api/views/asset.py` - All methods use new `@asset_docs` helpers
- `plane/api/views/project.py` - Import updated
- `plane/api/views/user.py` - Import updated
- `plane/api/views/state.py` - Import updated
- `plane/api/views/intake.py` - Import updated
- `plane/api/views/member.py` - Import updated
- `plane/api/views/module.py` - Import updated
- `plane/api/views/cycle.py` - Import updated
- `plane/api/views/issue.py` - Import updated
- `plane/settings/common.py` - Hook paths updated
- `plane/api/apps.py` - Auth extension import updated
## Benefits
1. **Better Organization**: Related functionality is grouped together
2. **Easier Maintenance**: Changes to specific areas only affect relevant files
3. **Improved Discoverability**: Clear module names make it easy to find what you need
4. **Backwards Compatibility**: All existing imports continue to work
5. **Reduced Coupling**: Import only what you need from specific modules
6. **Consistent Documentation**: All endpoints now use standardized helpers
7. **Massive Code Reduction**: ~80% reduction in decorator bloat using reusable components
plane-src/apps/api/plane/utils/openapi/__init__.py
+341
View File
@@ -0,0 +1,341 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
OpenAPI utilities for drf-spectacular integration.
This module provides reusable components for API documentation:
- Authentication extensions
- Common parameters and responses
- Helper decorators
- Schema preprocessing hooks
- Examples
"""
# Authentication extensions
from .auth import APIKeyAuthenticationExtension
# Parameters
from .parameters import (
WORKSPACE_SLUG_PARAMETER,
PROJECT_ID_PARAMETER,
PROJECT_PK_PARAMETER,
PROJECT_IDENTIFIER_PARAMETER,
ISSUE_IDENTIFIER_PARAMETER,
ASSET_ID_PARAMETER,
CYCLE_ID_PARAMETER,
MODULE_ID_PARAMETER,
MODULE_PK_PARAMETER,
ISSUE_ID_PARAMETER,
STATE_ID_PARAMETER,
LABEL_ID_PARAMETER,
COMMENT_ID_PARAMETER,
LINK_ID_PARAMETER,
ATTACHMENT_ID_PARAMETER,
ACTIVITY_ID_PARAMETER,
CURSOR_PARAMETER,
PER_PAGE_PARAMETER,
EXTERNAL_ID_PARAMETER,
EXTERNAL_SOURCE_PARAMETER,
ORDER_BY_PARAMETER,
SEARCH_PARAMETER,
SEARCH_PARAMETER_REQUIRED,
LIMIT_PARAMETER,
WORKSPACE_SEARCH_PARAMETER,
PROJECT_ID_QUERY_PARAMETER,
CYCLE_VIEW_PARAMETER,
FIELDS_PARAMETER,
EXPAND_PARAMETER,
ESTIMATE_ID_PARAMETER,
)
# Responses
from .responses import (
UNAUTHORIZED_RESPONSE,
FORBIDDEN_RESPONSE,
NOT_FOUND_RESPONSE,
VALIDATION_ERROR_RESPONSE,
DELETED_RESPONSE,
ARCHIVED_RESPONSE,
UNARCHIVED_RESPONSE,
INVALID_REQUEST_RESPONSE,
CONFLICT_RESPONSE,
ADMIN_ONLY_RESPONSE,
CANNOT_DELETE_RESPONSE,
CANNOT_ARCHIVE_RESPONSE,
REQUIRED_FIELDS_RESPONSE,
PROJECT_NOT_FOUND_RESPONSE,
WORKSPACE_NOT_FOUND_RESPONSE,
PROJECT_NAME_TAKEN_RESPONSE,
ISSUE_NOT_FOUND_RESPONSE,
WORK_ITEM_NOT_FOUND_RESPONSE,
EXTERNAL_ID_EXISTS_RESPONSE,
LABEL_NOT_FOUND_RESPONSE,
LABEL_NAME_EXISTS_RESPONSE,
MODULE_NOT_FOUND_RESPONSE,
MODULE_ISSUE_NOT_FOUND_RESPONSE,
CYCLE_CANNOT_ARCHIVE_RESPONSE,
STATE_NAME_EXISTS_RESPONSE,
STATE_CANNOT_DELETE_RESPONSE,
COMMENT_NOT_FOUND_RESPONSE,
LINK_NOT_FOUND_RESPONSE,
ATTACHMENT_NOT_FOUND_RESPONSE,
BAD_SEARCH_REQUEST_RESPONSE,
PRESIGNED_URL_SUCCESS_RESPONSE,
GENERIC_ASSET_UPLOAD_SUCCESS_RESPONSE,
GENERIC_ASSET_VALIDATION_ERROR_RESPONSE,
ASSET_CONFLICT_RESPONSE,
ASSET_DOWNLOAD_SUCCESS_RESPONSE,
ASSET_DOWNLOAD_ERROR_RESPONSE,
ASSET_UPDATED_RESPONSE,
ASSET_DELETED_RESPONSE,
ASSET_NOT_FOUND_RESPONSE,
create_paginated_response,
)
# Examples
from .examples import (
FILE_UPLOAD_EXAMPLE,
WORKSPACE_EXAMPLE,
PROJECT_EXAMPLE,
ISSUE_EXAMPLE,
USER_EXAMPLE,
get_sample_for_schema,
# Request Examples
ISSUE_CREATE_EXAMPLE,
ISSUE_UPDATE_EXAMPLE,
ISSUE_UPSERT_EXAMPLE,
LABEL_CREATE_EXAMPLE,
LABEL_UPDATE_EXAMPLE,
ISSUE_LINK_CREATE_EXAMPLE,
ISSUE_LINK_UPDATE_EXAMPLE,
ISSUE_COMMENT_CREATE_EXAMPLE,
ISSUE_COMMENT_UPDATE_EXAMPLE,
ISSUE_ATTACHMENT_UPLOAD_EXAMPLE,
ATTACHMENT_UPLOAD_CONFIRM_EXAMPLE,
CYCLE_CREATE_EXAMPLE,
CYCLE_UPDATE_EXAMPLE,
CYCLE_ISSUE_REQUEST_EXAMPLE,
TRANSFER_CYCLE_ISSUE_EXAMPLE,
MODULE_CREATE_EXAMPLE,
MODULE_UPDATE_EXAMPLE,
MODULE_ISSUE_REQUEST_EXAMPLE,
PROJECT_CREATE_EXAMPLE,
PROJECT_UPDATE_EXAMPLE,
STATE_CREATE_EXAMPLE,
STATE_UPDATE_EXAMPLE,
INTAKE_ISSUE_CREATE_EXAMPLE,
INTAKE_ISSUE_UPDATE_EXAMPLE,
ESTIMATE_CREATE_EXAMPLE,
ESTIMATE_UPDATE_EXAMPLE,
ESTIMATE_POINT_CREATE_EXAMPLE,
ESTIMATE_POINT_UPDATE_EXAMPLE,
# Response Examples
CYCLE_EXAMPLE,
TRANSFER_CYCLE_ISSUE_SUCCESS_EXAMPLE,
TRANSFER_CYCLE_ISSUE_ERROR_EXAMPLE,
TRANSFER_CYCLE_COMPLETED_ERROR_EXAMPLE,
MODULE_EXAMPLE,
STATE_EXAMPLE,
LABEL_EXAMPLE,
ISSUE_LINK_EXAMPLE,
ISSUE_COMMENT_EXAMPLE,
ISSUE_ATTACHMENT_EXAMPLE,
ISSUE_ATTACHMENT_NOT_UPLOADED_EXAMPLE,
INTAKE_ISSUE_EXAMPLE,
MODULE_ISSUE_EXAMPLE,
ISSUE_SEARCH_EXAMPLE,
WORKSPACE_MEMBER_EXAMPLE,
PROJECT_MEMBER_EXAMPLE,
CYCLE_ISSUE_EXAMPLE,
STICKY_EXAMPLE,
ESTIMATE_EXAMPLE,
ESTIMATE_POINT_EXAMPLE,
)
# Helper decorators
from .decorators import (
workspace_docs,
project_docs,
issue_docs,
intake_docs,
asset_docs,
user_docs,
cycle_docs,
work_item_docs,
work_item_relation_docs,
label_docs,
issue_link_docs,
issue_comment_docs,
issue_activity_docs,
issue_attachment_docs,
module_docs,
module_issue_docs,
state_docs,
estimate_docs,
estimate_point_docs,
)
# Schema processing hooks
from .hooks import (
preprocess_filter_api_v1_paths,
generate_operation_summary,
)
__all__ = [
# Authentication
"APIKeyAuthenticationExtension",
# Parameters
"WORKSPACE_SLUG_PARAMETER",
"PROJECT_ID_PARAMETER",
"PROJECT_PK_PARAMETER",
"PROJECT_IDENTIFIER_PARAMETER",
"ISSUE_IDENTIFIER_PARAMETER",
"ASSET_ID_PARAMETER",
"CYCLE_ID_PARAMETER",
"MODULE_ID_PARAMETER",
"MODULE_PK_PARAMETER",
"ISSUE_ID_PARAMETER",
"STATE_ID_PARAMETER",
"LABEL_ID_PARAMETER",
"COMMENT_ID_PARAMETER",
"LINK_ID_PARAMETER",
"ATTACHMENT_ID_PARAMETER",
"ACTIVITY_ID_PARAMETER",
"CURSOR_PARAMETER",
"PER_PAGE_PARAMETER",
"EXTERNAL_ID_PARAMETER",
"EXTERNAL_SOURCE_PARAMETER",
"ORDER_BY_PARAMETER",
"SEARCH_PARAMETER",
"SEARCH_PARAMETER_REQUIRED",
"LIMIT_PARAMETER",
"WORKSPACE_SEARCH_PARAMETER",
"PROJECT_ID_QUERY_PARAMETER",
"CYCLE_VIEW_PARAMETER",
"FIELDS_PARAMETER",
"EXPAND_PARAMETER",
"ESTIMATE_ID_PARAMETER",
# Responses
"UNAUTHORIZED_RESPONSE",
"FORBIDDEN_RESPONSE",
"NOT_FOUND_RESPONSE",
"VALIDATION_ERROR_RESPONSE",
"DELETED_RESPONSE",
"ARCHIVED_RESPONSE",
"UNARCHIVED_RESPONSE",
"INVALID_REQUEST_RESPONSE",
"CONFLICT_RESPONSE",
"ADMIN_ONLY_RESPONSE",
"CANNOT_DELETE_RESPONSE",
"CANNOT_ARCHIVE_RESPONSE",
"REQUIRED_FIELDS_RESPONSE",
"PROJECT_NOT_FOUND_RESPONSE",
"WORKSPACE_NOT_FOUND_RESPONSE",
"PROJECT_NAME_TAKEN_RESPONSE",
"ISSUE_NOT_FOUND_RESPONSE",
"WORK_ITEM_NOT_FOUND_RESPONSE",
"EXTERNAL_ID_EXISTS_RESPONSE",
"LABEL_NOT_FOUND_RESPONSE",
"LABEL_NAME_EXISTS_RESPONSE",
"MODULE_NOT_FOUND_RESPONSE",
"MODULE_ISSUE_NOT_FOUND_RESPONSE",
"CYCLE_CANNOT_ARCHIVE_RESPONSE",
"STATE_NAME_EXISTS_RESPONSE",
"STATE_CANNOT_DELETE_RESPONSE",
"COMMENT_NOT_FOUND_RESPONSE",
"LINK_NOT_FOUND_RESPONSE",
"ATTACHMENT_NOT_FOUND_RESPONSE",
"BAD_SEARCH_REQUEST_RESPONSE",
"create_paginated_response",
"PRESIGNED_URL_SUCCESS_RESPONSE",
"GENERIC_ASSET_UPLOAD_SUCCESS_RESPONSE",
"GENERIC_ASSET_VALIDATION_ERROR_RESPONSE",
"ASSET_CONFLICT_RESPONSE",
"ASSET_DOWNLOAD_SUCCESS_RESPONSE",
"ASSET_DOWNLOAD_ERROR_RESPONSE",
"ASSET_UPDATED_RESPONSE",
"ASSET_DELETED_RESPONSE",
"ASSET_NOT_FOUND_RESPONSE",
# Examples
"FILE_UPLOAD_EXAMPLE",
"WORKSPACE_EXAMPLE",
"PROJECT_EXAMPLE",
"ISSUE_EXAMPLE",
"USER_EXAMPLE",
"get_sample_for_schema",
# Request Examples
"ISSUE_CREATE_EXAMPLE",
"ISSUE_UPDATE_EXAMPLE",
"ISSUE_UPSERT_EXAMPLE",
"LABEL_CREATE_EXAMPLE",
"LABEL_UPDATE_EXAMPLE",
"ISSUE_LINK_CREATE_EXAMPLE",
"ISSUE_LINK_UPDATE_EXAMPLE",
"ISSUE_COMMENT_CREATE_EXAMPLE",
"ISSUE_COMMENT_UPDATE_EXAMPLE",
"ISSUE_ATTACHMENT_UPLOAD_EXAMPLE",
"ATTACHMENT_UPLOAD_CONFIRM_EXAMPLE",
"CYCLE_CREATE_EXAMPLE",
"CYCLE_UPDATE_EXAMPLE",
"CYCLE_ISSUE_REQUEST_EXAMPLE",
"TRANSFER_CYCLE_ISSUE_EXAMPLE",
"MODULE_CREATE_EXAMPLE",
"MODULE_UPDATE_EXAMPLE",
"MODULE_ISSUE_REQUEST_EXAMPLE",
"PROJECT_CREATE_EXAMPLE",
"PROJECT_UPDATE_EXAMPLE",
"STATE_CREATE_EXAMPLE",
"STATE_UPDATE_EXAMPLE",
"INTAKE_ISSUE_CREATE_EXAMPLE",
"INTAKE_ISSUE_UPDATE_EXAMPLE",
"ESTIMATE_CREATE_EXAMPLE",
"ESTIMATE_UPDATE_EXAMPLE",
"ESTIMATE_POINT_CREATE_EXAMPLE",
"ESTIMATE_POINT_UPDATE_EXAMPLE",
# Response Examples
"CYCLE_EXAMPLE",
"TRANSFER_CYCLE_ISSUE_SUCCESS_EXAMPLE",
"TRANSFER_CYCLE_ISSUE_ERROR_EXAMPLE",
"TRANSFER_CYCLE_COMPLETED_ERROR_EXAMPLE",
"MODULE_EXAMPLE",
"STATE_EXAMPLE",
"LABEL_EXAMPLE",
"ISSUE_LINK_EXAMPLE",
"ISSUE_COMMENT_EXAMPLE",
"ISSUE_ATTACHMENT_EXAMPLE",
"ISSUE_ATTACHMENT_NOT_UPLOADED_EXAMPLE",
"INTAKE_ISSUE_EXAMPLE",
"MODULE_ISSUE_EXAMPLE",
"ISSUE_SEARCH_EXAMPLE",
"WORKSPACE_MEMBER_EXAMPLE",
"PROJECT_MEMBER_EXAMPLE",
"CYCLE_ISSUE_EXAMPLE",
"STICKY_EXAMPLE",
"ESTIMATE_EXAMPLE",
"ESTIMATE_POINT_EXAMPLE",
# Decorators
"workspace_docs",
"project_docs",
"issue_docs",
"intake_docs",
"asset_docs",
"user_docs",
"cycle_docs",
"work_item_docs",
"work_item_relation_docs",
"label_docs",
"issue_link_docs",
"issue_comment_docs",
"issue_activity_docs",
"issue_attachment_docs",
"module_docs",
"module_issue_docs",
"state_docs",
"estimate_docs",
"estimate_point_docs",
# Hooks
"preprocess_filter_api_v1_paths",
"generate_operation_summary",
]
plane-src/apps/api/plane/utils/openapi/auth.py
+34
View File
@@ -0,0 +1,34 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
OpenAPI authentication extensions for drf-spectacular.
This module provides authentication extensions that automatically register
custom authentication classes with the OpenAPI schema generator.
"""
from drf_spectacular.extensions import OpenApiAuthenticationExtension
class APIKeyAuthenticationExtension(OpenApiAuthenticationExtension):
"""
OpenAPI authentication extension for
plane.api.middleware.api_authentication.APIKeyAuthentication
"""
target_class = "plane.api.middleware.api_authentication.APIKeyAuthentication"
name = "ApiKeyAuthentication"
priority = 1
def get_security_definition(self, auto_schema):
"""
Return the security definition for API key authentication.
"""
return {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key authentication. Provide your API key in the X-API-Key header.", # noqa: E501
}
plane-src/apps/api/plane/utils/openapi/decorators.py
+325
View File
@@ -0,0 +1,325 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
Helper decorators for drf-spectacular OpenAPI documentation.
This module provides domain-specific decorators that apply common
parameters, responses, and tags to API endpoints based on their context.
"""
from drf_spectacular.utils import extend_schema
from .parameters import WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER
from .responses import UNAUTHORIZED_RESPONSE, FORBIDDEN_RESPONSE, NOT_FOUND_RESPONSE
def _merge_schema_options(defaults, kwargs):
"""Helper function to merge responses and parameters from kwargs into defaults"""
# Merge responses
if "responses" in kwargs:
defaults["responses"].update(kwargs["responses"])
kwargs = {k: v for k, v in kwargs.items() if k != "responses"}
# Merge parameters
if "parameters" in kwargs:
defaults["parameters"].extend(kwargs["parameters"])
kwargs = {k: v for k, v in kwargs.items() if k != "parameters"}
defaults.update(kwargs)
return defaults
def user_docs(**kwargs):
"""Decorator for user-related endpoints"""
defaults = {
"tags": ["Users"],
"parameters": [],
"responses": {
401: UNAUTHORIZED_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def workspace_docs(**kwargs):
"""Decorator for workspace-related endpoints"""
defaults = {
"tags": ["Workspaces"],
"parameters": [WORKSPACE_SLUG_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def project_docs(**kwargs):
"""Decorator for project-related endpoints"""
defaults = {
"tags": ["Projects"],
"parameters": [WORKSPACE_SLUG_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def cycle_docs(**kwargs):
"""Decorator for cycle-related endpoints"""
defaults = {
"tags": ["Cycles"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def issue_docs(**kwargs):
"""Decorator for issue-related endpoints"""
defaults = {
"tags": ["Work Items"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def intake_docs(**kwargs):
"""Decorator for intake-related endpoints"""
defaults = {
"tags": ["Intake"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def asset_docs(**kwargs):
"""Decorator for asset-related endpoints with common defaults"""
defaults = {
"tags": ["Assets"],
"parameters": [],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
# Issue-related decorators for specific tags
def work_item_docs(**kwargs):
"""Decorator for work item endpoints (main issue operations)"""
defaults = {
"tags": ["Work Items"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def label_docs(**kwargs):
"""Decorator for label management endpoints"""
defaults = {
"tags": ["Labels"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def issue_link_docs(**kwargs):
"""Decorator for issue link endpoints"""
defaults = {
"tags": ["Work Item Links"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def issue_comment_docs(**kwargs):
"""Decorator for issue comment endpoints"""
defaults = {
"tags": ["Work Item Comments"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def issue_activity_docs(**kwargs):
"""Decorator for issue activity/search endpoints"""
defaults = {
"tags": ["Work Item Activity"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def issue_attachment_docs(**kwargs):
"""Decorator for issue attachment endpoints"""
defaults = {
"tags": ["Work Item Attachments"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def work_item_relation_docs(**kwargs):
"""Decorator for work item relation endpoints"""
defaults = {
"tags": ["Work Item Relations"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def module_docs(**kwargs):
"""Decorator for module management endpoints"""
defaults = {
"tags": ["Modules"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def module_issue_docs(**kwargs):
"""Decorator for module issue management endpoints"""
defaults = {
"tags": ["Modules"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def state_docs(**kwargs):
"""Decorator for state management endpoints"""
defaults = {
"tags": ["States"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def sticky_docs(**kwargs):
"""Decorator for sticky management endpoints"""
defaults = {
"tags": ["Stickies"],
"summary": "Endpoints for sticky create/update/delete and fetch sticky details",
"parameters": [WORKSPACE_SLUG_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def estimate_docs(**kwargs):
"""Decorator for estimate-related endpoints"""
defaults = {
"tags": ["Estimates"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
def estimate_point_docs(**kwargs):
"""Decorator for estimate point-related endpoints"""
defaults = {
"tags": ["Estimate Points"],
"parameters": [WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER],
"responses": {
401: UNAUTHORIZED_RESPONSE,
403: FORBIDDEN_RESPONSE,
404: NOT_FOUND_RESPONSE,
},
}
return extend_schema(**_merge_schema_options(defaults, kwargs))
plane-src/apps/api/plane/utils/openapi/examples.py
+920
View File
@@ -0,0 +1,920 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
Common OpenAPI examples for drf-spectacular.
This module provides reusable example data for API responses and requests
to make the generated documentation more helpful and realistic.
"""
from drf_spectacular.utils import OpenApiExample
# File Upload Examples
FILE_UPLOAD_EXAMPLE = OpenApiExample(
name="File Upload Success",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"asset": "uploads/workspace_1/file_example.pdf",
"attributes": {
"name": "example-document.pdf",
"size": 1024000,
"mimetype": "application/pdf",
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
},
)
# Workspace Examples
WORKSPACE_EXAMPLE = OpenApiExample(
name="Workspace",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Workspace",
"slug": "my-workspace",
"organization_size": "1-10",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
},
)
# Project Examples
PROJECT_EXAMPLE = OpenApiExample(
name="Project",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Mobile App Development",
"description": "Development of the mobile application",
"identifier": "MAD",
"network": 2,
"project_lead": "550e8400-e29b-41d4-a716-446655440001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
},
)
# Issue Examples
ISSUE_EXAMPLE = OpenApiExample(
name="Issue",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Implement user authentication",
"description": "Add OAuth 2.0 authentication flow",
"sequence_id": 1,
"priority": "high",
"assignees": ["550e8400-e29b-41d4-a716-446655440001"],
"labels": ["550e8400-e29b-41d4-a716-446655440002"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
},
)
# User Examples
USER_EXAMPLE = OpenApiExample(
name="User",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"avatar": "https://example.com/avatar.jpg",
"avatar_url": "https://example.com/avatar.jpg",
"display_name": "John Doe",
},
)
# ============================================================================
# REQUEST EXAMPLES - Centralized examples for API requests
# ============================================================================
# Work Item / Issue Examples
ISSUE_CREATE_EXAMPLE = OpenApiExample(
"IssueCreateSerializer",
value={
"name": "New Issue",
"description": "New issue description",
"priority": "medium",
"state": "0ec6cfa4-e906-4aad-9390-2df0303a41cd",
"assignees": ["0ec6cfa4-e906-4aad-9390-2df0303a41cd"],
"labels": ["0ec6cfa4-e906-4aad-9390-2df0303a41ce"],
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating a work item",
)
ISSUE_UPDATE_EXAMPLE = OpenApiExample(
"IssueUpdateSerializer",
value={
"name": "Updated Issue",
"description": "Updated issue description",
"priority": "medium",
"state": "0ec6cfa4-e906-4aad-9390-2df0303a41cd",
"assignees": ["0ec6cfa4-e906-4aad-9390-2df0303a41cd"],
"labels": ["0ec6cfa4-e906-4aad-9390-2df0303a41ce"],
},
description="Example request for updating a work item",
)
ISSUE_UPSERT_EXAMPLE = OpenApiExample(
"IssueUpsertSerializer",
value={
"name": "Updated Issue via External ID",
"description": "Updated issue description",
"priority": "high",
"state": "0ec6cfa4-e906-4aad-9390-2df0303a41cd",
"assignees": ["0ec6cfa4-e906-4aad-9390-2df0303a41cd"],
"labels": ["0ec6cfa4-e906-4aad-9390-2df0303a41ce"],
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for upserting a work item via external ID",
)
# Label Examples
LABEL_CREATE_EXAMPLE = OpenApiExample(
"LabelCreateUpdateSerializer",
value={
"name": "New Label",
"color": "#ff0000",
"description": "New label description",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating a label",
)
LABEL_UPDATE_EXAMPLE = OpenApiExample(
"LabelCreateUpdateSerializer",
value={
"name": "Updated Label",
"color": "#00ff00",
"description": "Updated label description",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for updating a label",
)
# Issue Link Examples
ISSUE_LINK_CREATE_EXAMPLE = OpenApiExample(
"IssueLinkCreateSerializer",
value={
"url": "https://example.com",
"title": "Example Link",
},
description="Example request for creating an issue link",
)
ISSUE_LINK_UPDATE_EXAMPLE = OpenApiExample(
"IssueLinkUpdateSerializer",
value={
"url": "https://example.com",
"title": "Updated Link",
},
description="Example request for updating an issue link",
)
# Issue Comment Examples
ISSUE_COMMENT_CREATE_EXAMPLE = OpenApiExample(
"IssueCommentCreateSerializer",
value={
"comment_html": "<p>New comment content</p>",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating an issue comment",
)
ISSUE_COMMENT_UPDATE_EXAMPLE = OpenApiExample(
"IssueCommentCreateSerializer",
value={
"comment_html": "<p>Updated comment content</p>",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for updating an issue comment",
)
# Issue Attachment Examples
ISSUE_ATTACHMENT_UPLOAD_EXAMPLE = OpenApiExample(
"IssueAttachmentUploadSerializer",
value={
"name": "document.pdf",
"type": "application/pdf",
"size": 1024000,
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating an issue attachment",
)
ATTACHMENT_UPLOAD_CONFIRM_EXAMPLE = OpenApiExample(
"ConfirmUpload",
value={"is_uploaded": True},
description="Confirm that the attachment has been successfully uploaded",
)
# Cycle Examples
CYCLE_CREATE_EXAMPLE = OpenApiExample(
"CycleCreateSerializer",
value={
"name": "Cycle 1",
"description": "Cycle 1 description",
"start_date": "2021-01-01",
"end_date": "2021-01-31",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating a cycle",
)
CYCLE_UPDATE_EXAMPLE = OpenApiExample(
"CycleUpdateSerializer",
value={
"name": "Updated Cycle",
"description": "Updated cycle description",
"start_date": "2021-01-01",
"end_date": "2021-01-31",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for updating a cycle",
)
CYCLE_ISSUE_REQUEST_EXAMPLE = OpenApiExample(
"CycleIssueRequestSerializer",
value={
"issues": [
"0ec6cfa4-e906-4aad-9390-2df0303a41cd",
"0ec6cfa4-e906-4aad-9390-2df0303a41ce",
],
},
description="Example request for adding cycle issues",
)
TRANSFER_CYCLE_ISSUE_EXAMPLE = OpenApiExample(
"TransferCycleIssueRequestSerializer",
value={
"new_cycle_id": "0ec6cfa4-e906-4aad-9390-2df0303a41ce",
},
description="Example request for transferring cycle issues",
)
# Module Examples
MODULE_CREATE_EXAMPLE = OpenApiExample(
"ModuleCreateSerializer",
value={
"name": "New Module",
"description": "New module description",
"start_date": "2021-01-01",
"end_date": "2021-01-31",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating a module",
)
MODULE_UPDATE_EXAMPLE = OpenApiExample(
"ModuleUpdateSerializer",
value={
"name": "Updated Module",
"description": "Updated module description",
"start_date": "2021-01-01",
"end_date": "2021-01-31",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for updating a module",
)
MODULE_ISSUE_REQUEST_EXAMPLE = OpenApiExample(
"ModuleIssueRequestSerializer",
value={
"issues": [
"0ec6cfa4-e906-4aad-9390-2df0303a41cd",
"0ec6cfa4-e906-4aad-9390-2df0303a41ce",
],
},
description="Example request for adding module issues",
)
# Project Examples
PROJECT_CREATE_EXAMPLE = OpenApiExample(
"ProjectCreateSerializer",
value={
"name": "New Project",
"description": "New project description",
"identifier": "new-project",
"project_lead": "0ec6cfa4-e906-4aad-9390-2df0303a41ce",
},
description="Example request for creating a project",
)
PROJECT_UPDATE_EXAMPLE = OpenApiExample(
"ProjectUpdateSerializer",
value={
"name": "Updated Project",
"description": "Updated project description",
"identifier": "updated-project",
"project_lead": "0ec6cfa4-e906-4aad-9390-2df0303a41ce",
},
description="Example request for updating a project",
)
# State Examples
STATE_CREATE_EXAMPLE = OpenApiExample(
"StateCreateSerializer",
value={
"name": "New State",
"color": "#ff0000",
"group": "backlog",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for creating a state",
)
STATE_UPDATE_EXAMPLE = OpenApiExample(
"StateUpdateSerializer",
value={
"name": "Updated State",
"color": "#00ff00",
"group": "backlog",
"external_id": "1234567890",
"external_source": "github",
},
description="Example request for updating a state",
)
# Intake Examples
INTAKE_ISSUE_CREATE_EXAMPLE = OpenApiExample(
"IntakeIssueCreateSerializer",
value={
"issue": {
"name": "New Issue",
"description": "New issue description",
"priority": "medium",
}
},
description="Example request for creating an intake issue",
)
INTAKE_ISSUE_UPDATE_EXAMPLE = OpenApiExample(
"IntakeIssueUpdateSerializer",
value={
"status": 1,
"issue": {
"name": "Updated Issue",
"description": "Updated issue description",
"priority": "high",
},
},
description="Example request for updating an intake issue",
)
# ============================================================================
# RESPONSE EXAMPLES - Centralized examples for API responses
# ============================================================================
# Cycle Response Examples
CYCLE_EXAMPLE = OpenApiExample(
name="Cycle",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sprint 1 - Q1 2024",
"description": "First sprint of the quarter focusing on core features",
"start_date": "2024-01-01",
"end_date": "2024-01-14",
"status": "current",
"total_issues": 15,
"completed_issues": 8,
"cancelled_issues": 1,
"started_issues": 4,
"unstarted_issues": 2,
"backlog_issues": 0,
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Transfer Cycle Issue Response Examples
TRANSFER_CYCLE_ISSUE_SUCCESS_EXAMPLE = OpenApiExample(
name="Transfer Cycle Issue Success",
value={
"message": "Success",
},
description="Successful transfer of cycle issues to new cycle",
)
TRANSFER_CYCLE_ISSUE_ERROR_EXAMPLE = OpenApiExample(
name="Transfer Cycle Issue Error",
value={
"error": "New Cycle Id is required",
},
description="Error when required cycle ID is missing",
)
TRANSFER_CYCLE_COMPLETED_ERROR_EXAMPLE = OpenApiExample(
name="Transfer to Completed Cycle Error",
value={
"error": "The cycle where the issues are transferred is already completed",
},
description="Error when trying to transfer to a completed cycle",
)
# Module Response Examples
MODULE_EXAMPLE = OpenApiExample(
name="Module",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Authentication Module",
"description": "User authentication and authorization features",
"start_date": "2024-01-01",
"target_date": "2024-02-15",
"status": "in-progress",
"total_issues": 12,
"completed_issues": 5,
"cancelled_issues": 0,
"started_issues": 4,
"unstarted_issues": 3,
"backlog_issues": 0,
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# State Response Examples
STATE_EXAMPLE = OpenApiExample(
name="State",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "In Progress",
"color": "#f39c12",
"group": "started",
"sequence": 2,
"default": False,
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Label Response Examples
LABEL_EXAMPLE = OpenApiExample(
name="Label",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "bug",
"color": "#ff4444",
"description": "Issues that represent bugs in the system",
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Issue Link Response Examples
ISSUE_LINK_EXAMPLE = OpenApiExample(
name="IssueLink",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://github.com/example/repo/pull/123",
"title": "Fix authentication bug",
"metadata": {
"title": "Fix authentication bug",
"description": "Pull request to fix authentication timeout issue",
"image": "https://github.com/example/repo/avatar.png",
},
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Issue Comment Response Examples
ISSUE_COMMENT_EXAMPLE = OpenApiExample(
name="IssueComment",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"comment_html": "<p>This issue has been resolved by implementing OAuth 2.0 flow.</p>", # noqa: E501
"comment_json": {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This issue has been resolved by implementing OAuth 2.0 flow.", # noqa: E501
}
],
}
],
},
"actor": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"first_name": "John",
"last_name": "Doe",
"display_name": "John Doe",
"avatar": "https://example.com/avatar.jpg",
},
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Issue Attachment Response Examples
ISSUE_ATTACHMENT_EXAMPLE = OpenApiExample(
name="IssueAttachment",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "screenshot.png",
"size": 1024000,
"asset_url": "https://s3.amazonaws.com/bucket/screenshot.png?signed-url",
"attributes": {
"name": "screenshot.png",
"type": "image/png",
"size": 1024000,
},
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Issue Attachment Error Response Examples
ISSUE_ATTACHMENT_NOT_UPLOADED_EXAMPLE = OpenApiExample(
name="Issue Attachment Not Uploaded",
value={
"error": "The asset is not uploaded.",
"status": False,
},
description="Error when trying to download an attachment that hasn't been uploaded yet", # noqa: E501
)
# Intake Issue Response Examples
INTAKE_ISSUE_EXAMPLE = OpenApiExample(
name="IntakeIssue",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": 0, # Pending
"source": "in_app",
"issue": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Feature request: Dark mode",
"description": "Add dark mode support to the application",
"priority": "medium",
"sequence_id": 124,
},
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Module Issue Response Examples
MODULE_ISSUE_EXAMPLE = OpenApiExample(
name="ModuleIssue",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"module": "550e8400-e29b-41d4-a716-446655440001",
"issue": "550e8400-e29b-41d4-a716-446655440002",
"sub_issues_count": 2,
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
# Issue Search Response Examples
ISSUE_SEARCH_EXAMPLE = OpenApiExample(
name="IssueSearchResults",
value={
"issues": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Fix authentication bug in user login",
"sequence_id": 123,
"project__identifier": "MAB",
"project_id": "550e8400-e29b-41d4-a716-446655440001",
"workspace__slug": "my-workspace",
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Add authentication middleware",
"sequence_id": 124,
"project__identifier": "MAB",
"project_id": "550e8400-e29b-41d4-a716-446655440001",
"workspace__slug": "my-workspace",
},
]
},
)
# Workspace Member Response Examples
WORKSPACE_MEMBER_EXAMPLE = OpenApiExample(
name="WorkspaceMembers",
value=[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "John",
"last_name": "Doe",
"display_name": "John Doe",
"email": "john.doe@example.com",
"avatar": "https://example.com/avatar.jpg",
"role": 20,
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"first_name": "Jane",
"last_name": "Smith",
"display_name": "Jane Smith",
"email": "jane.smith@example.com",
"avatar": "https://example.com/avatar2.jpg",
"role": 15,
},
],
)
# Project Member Response Examples
PROJECT_MEMBER_EXAMPLE = OpenApiExample(
name="ProjectMembers",
value=[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "John",
"last_name": "Doe",
"display_name": "John Doe",
"email": "john.doe@example.com",
"avatar": "https://example.com/avatar.jpg",
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"first_name": "Jane",
"last_name": "Smith",
"display_name": "Jane Smith",
"email": "jane.smith@example.com",
"avatar": "https://example.com/avatar2.jpg",
},
],
)
# Cycle Issue Response Examples
CYCLE_ISSUE_EXAMPLE = OpenApiExample(
name="CycleIssue",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"cycle": "550e8400-e29b-41d4-a716-446655440001",
"issue": "550e8400-e29b-41d4-a716-446655440002",
"sub_issues_count": 3,
"created_at": "2024-01-01T10:30:00Z",
"updated_at": "2024-01-10T15:45:00Z",
},
)
STICKY_EXAMPLE = OpenApiExample(
name="Sticky",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sticky 1",
"description_html": "<p>Sticky 1 description</p>",
"created_at": "2024-01-01T10:30:00Z",
},
)
# Estimate Examples
ESTIMATE_EXAMPLE = OpenApiExample(
name="Estimate",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Estimate 1",
"description": "Estimate 1 description",
},
description="Example response for an estimate",
)
ESTIMATE_POINT_EXAMPLE = OpenApiExample(
name="EstimatePoint",
value={
"id": "550e8400-e29b-41d4-a716-446655440000",
"estimate": "550e8400-e29b-41d4-a716-446655440001",
"key": 1,
"value": "1",
},
description="Example response for an estimate point",
)
ESTIMATE_CREATE_EXAMPLE = OpenApiExample(
name="EstimateCreateSerializer",
value={
"name": "Estimate 1",
"description": "Estimate 1 description",
},
description="Example request for creating an estimate",
)
ESTIMATE_UPDATE_EXAMPLE = OpenApiExample(
name="EstimateUpdateSerializer",
value={
"name": "Estimate 1",
"description": "Estimate 1 description",
},
description="Example request for updating an estimate",
)
# Estimate Point Examples
ESTIMATE_POINT_CREATE_EXAMPLE = OpenApiExample(
name="EstimatePointCreateSerializer",
value=[
{
"value": "1",
"description": "Estimate Point 1 description",
},
{
"value": "2",
"description": "Estimate Point 2 description",
},
],
description="Example request for creating an estimate point",
)
ESTIMATE_POINT_UPDATE_EXAMPLE = OpenApiExample(
name="EstimatePointUpdateSerializer",
value={
"value": "1",
"description": "Estimate Point 1 description",
},
description="Example request for updating an estimate point",
)
# Sample data for different entity types
SAMPLE_ISSUE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Fix authentication bug in user login",
"description": "Users are unable to log in due to authentication service timeout",
"priority": "high",
"sequence_id": 123,
"state": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "In Progress",
"group": "started",
},
"assignees": [],
"labels": [],
"created_at": "2024-01-15T10:30:00Z",
}
SAMPLE_LABEL = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "bug",
"color": "#ff4444",
"description": "Issues that represent bugs in the system",
}
SAMPLE_CYCLE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sprint 1 - Q1 2024",
"description": "First sprint of the quarter focusing on core features",
"start_date": "2024-01-01",
"end_date": "2024-01-14",
"status": "current",
}
SAMPLE_MODULE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Authentication Module",
"description": "User authentication and authorization features",
"start_date": "2024-01-01",
"target_date": "2024-02-15",
"status": "in_progress",
}
SAMPLE_PROJECT = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Mobile App Backend",
"description": "Backend services for the mobile application",
"identifier": "MAB",
"network": 2,
}
SAMPLE_STATE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "In Progress",
"color": "#ffa500",
"group": "started",
"sequence": 2,
}
SAMPLE_COMMENT = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"comment_html": "<p>This issue needs more investigation. I'll look into the database connection timeout.</p>", # noqa: E501
"created_at": "2024-01-15T14:20:00Z",
"actor": {"id": "550e8400-e29b-41d4-a716-446655440002", "display_name": "John Doe"},
}
SAMPLE_LINK = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://github.com/example/repo/pull/123",
"title": "Fix authentication timeout issue",
"metadata": {},
}
SAMPLE_ACTIVITY = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"field": "priority",
"old_value": "medium",
"new_value": "high",
"created_at": "2024-01-15T11:45:00Z",
"actor": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"display_name": "Jane Smith",
},
}
SAMPLE_INTAKE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": 0,
"issue": {
"id": "550e8400-e29b-41d4-a716-446655440003",
"name": "Feature request: Dark mode support",
},
"created_at": "2024-01-15T09:15:00Z",
}
SAMPLE_GENERIC = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sample Item",
"created_at": "2024-01-15T12:00:00Z",
}
SAMPLE_CYCLE_ISSUE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"cycle": "550e8400-e29b-41d4-a716-446655440001",
"issue": "550e8400-e29b-41d4-a716-446655440002",
"sub_issues_count": 3,
"created_at": "2024-01-01T10:30:00Z",
}
SAMPLE_STICKY = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sticky 1",
"description_html": "<p>Sticky 1 description</p>",
"created_at": "2024-01-01T10:30:00Z",
}
SAMPLE_ESTIMATE = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Estimate 1",
"description": "Estimate 1 description",
"type": "categories",
"last_used": False,
"created_at": "2024-01-01T10:30:00Z",
}
SAMPLE_ESTIMATE_POINT = {
"id": "550e8400-e29b-41d4-a716-446655440000",
"estimate": "550e8400-e29b-41d4-a716-446655440001",
"key": 1,
"value": "1",
"description": "Estimate Point 1 description",
"created_at": "2024-01-01T10:30:00Z",
}
# Mapping of schema types to sample data
SCHEMA_EXAMPLES = {
"Issue": SAMPLE_ISSUE,
"WorkItem": SAMPLE_ISSUE,
"Label": SAMPLE_LABEL,
"Cycle": SAMPLE_CYCLE,
"Module": SAMPLE_MODULE,
"Project": SAMPLE_PROJECT,
"State": SAMPLE_STATE,
"Comment": SAMPLE_COMMENT,
"Link": SAMPLE_LINK,
"Activity": SAMPLE_ACTIVITY,
"Intake": SAMPLE_INTAKE,
"CycleIssue": SAMPLE_CYCLE_ISSUE,
"Sticky": SAMPLE_STICKY,
"Estimate": SAMPLE_ESTIMATE,
"EstimatePoint": SAMPLE_ESTIMATE_POINT,
}
def get_sample_for_schema(schema_name):
"""
Get appropriate sample data for a schema type.
Args:
schema_name (str): Name of the schema (e.g., "PaginatedIssueResponse")
Returns:
dict: Sample data for the schema type
"""
# Extract base schema name from paginated responses
if schema_name.startswith("Paginated"):
base_name = schema_name.replace("Paginated", "").replace("Response", "")
return SCHEMA_EXAMPLES.get(base_name, SAMPLE_GENERIC)
return SCHEMA_EXAMPLES.get(schema_name, SAMPLE_GENERIC)
plane-src/apps/api/plane/utils/openapi/hooks.py
+56
View File
@@ -0,0 +1,56 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
Schema processing hooks for drf-spectacular OpenAPI generation.
This module provides preprocessing and postprocessing functions that modify
the generated OpenAPI schema to apply custom filtering, tagging, and other
transformations.
"""
def preprocess_filter_api_v1_paths(endpoints):
"""
Filter OpenAPI endpoints to only include /api/v1/ paths and exclude PUT methods.
"""
filtered = []
for path, path_regex, method, callback in endpoints:
# Only include paths that start with /api/v1/ and exclude PUT methods
if path.startswith("/api/v1/") and method.upper() != "PUT" and "server" not in path.lower():
filtered.append((path, path_regex, method, callback))
return filtered
def generate_operation_summary(method, path, tag):
"""
Generate a human-readable summary for an operation.
"""
# Extract the main resource from the path
path_parts = [part for part in path.split("/") if part and not part.startswith("{")]
if len(path_parts) > 0:
resource = path_parts[-1].replace("-", " ").title()
else:
resource = tag
# Generate summary based on method
method_summaries = {
"GET": f"Retrieve {resource}",
"POST": f"Create {resource}",
"PATCH": f"Update {resource}",
"DELETE": f"Delete {resource}",
}
# Handle specific cases
if "archive" in path.lower():
if method == "POST":
return f"Archive {tag.rstrip('s')}"
elif method == "DELETE":
return f"Unarchive {tag.rstrip('s')}"
if "transfer" in path.lower():
return f"Transfer {tag.rstrip('s')}"
return method_summaries.get(method, f"{method} {resource}")
plane-src/apps/api/plane/utils/openapi/parameters.py
+505
View File
@@ -0,0 +1,505 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
Common OpenAPI parameters for drf-spectacular.
This module provides reusable parameter definitions that can be shared
across multiple API endpoints to ensure consistency.
"""
from drf_spectacular.utils import OpenApiParameter, OpenApiExample
from drf_spectacular.types import OpenApiTypes
# Path Parameters
WORKSPACE_SLUG_PARAMETER = OpenApiParameter(
name="slug",
description="Workspace slug",
required=True,
type=OpenApiTypes.STR,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example workspace",
value="my-workspace",
description="A typical workspace slug",
)
],
)
PROJECT_ID_PARAMETER = OpenApiParameter(
name="project_id",
description="Project ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example project ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical project UUID",
)
],
)
PROJECT_PK_PARAMETER = OpenApiParameter(
name="pk",
description="Project ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example project ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical project UUID",
)
],
)
PROJECT_IDENTIFIER_PARAMETER = OpenApiParameter(
name="project_identifier",
description="Project identifier (unique string within workspace)",
required=True,
type=OpenApiTypes.STR,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example project identifier",
value="PROJ",
description="A typical project identifier",
)
],
)
ISSUE_IDENTIFIER_PARAMETER = OpenApiParameter(
name="issue_identifier",
description="Issue sequence ID (numeric identifier within project)",
required=True,
type=OpenApiTypes.INT,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example issue identifier",
value=123,
description="A typical issue sequence ID",
)
],
)
ASSET_ID_PARAMETER = OpenApiParameter(
name="asset_id",
description="Asset ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example asset ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical asset UUID",
)
],
)
CYCLE_ID_PARAMETER = OpenApiParameter(
name="cycle_id",
description="Cycle ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example cycle ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical cycle UUID",
)
],
)
MODULE_ID_PARAMETER = OpenApiParameter(
name="module_id",
description="Module ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example module ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical module UUID",
)
],
)
MODULE_PK_PARAMETER = OpenApiParameter(
name="pk",
description="Module ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example module ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical module UUID",
)
],
)
ISSUE_ID_PARAMETER = OpenApiParameter(
name="issue_id",
description="Issue ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example issue ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical issue UUID",
)
],
)
STATE_ID_PARAMETER = OpenApiParameter(
name="state_id",
description="State ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example state ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical state UUID",
)
],
)
# Additional Path Parameters
LABEL_ID_PARAMETER = OpenApiParameter(
name="pk",
description="Label ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example label ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical label UUID",
)
],
)
COMMENT_ID_PARAMETER = OpenApiParameter(
name="pk",
description="Comment ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example comment ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical comment UUID",
)
],
)
LINK_ID_PARAMETER = OpenApiParameter(
name="pk",
description="Link ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example link ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical link UUID",
)
],
)
ATTACHMENT_ID_PARAMETER = OpenApiParameter(
name="pk",
description="Attachment ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example attachment ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical attachment UUID",
)
],
)
ACTIVITY_ID_PARAMETER = OpenApiParameter(
name="pk",
description="Activity ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
examples=[
OpenApiExample(
name="Example activity ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="A typical activity UUID",
)
],
)
# Query Parameters
CURSOR_PARAMETER = OpenApiParameter(
name="cursor",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Pagination cursor for getting next set of results",
required=False,
examples=[
OpenApiExample(
name="Next page cursor",
value="20:1:0",
description="Cursor format: 'page_size:page_number:offset'",
)
],
)
PER_PAGE_PARAMETER = OpenApiParameter(
name="per_page",
type=OpenApiTypes.INT,
location=OpenApiParameter.QUERY,
description="Number of results per page (default: 20, max: 100)",
required=False,
examples=[
OpenApiExample(name="Default", value=20),
OpenApiExample(name="Maximum", value=100),
],
)
# External Integration Parameters
EXTERNAL_ID_PARAMETER = OpenApiParameter(
name="external_id",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="External system identifier for filtering or lookup",
required=False,
examples=[
OpenApiExample(
name="GitHub Issue",
value="1234567890",
description="GitHub issue number",
)
],
)
EXTERNAL_SOURCE_PARAMETER = OpenApiParameter(
name="external_source",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="External system source name for filtering or lookup",
required=False,
examples=[
OpenApiExample(
name="GitHub",
value="github",
description="GitHub integration source",
),
OpenApiExample(
name="Jira",
value="jira",
description="Jira integration source",
),
],
)
# Ordering Parameters
ORDER_BY_PARAMETER = OpenApiParameter(
name="order_by",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Field to order results by. Prefix with '-' for descending order",
required=False,
examples=[
OpenApiExample(
name="Created date descending",
value="-created_at",
description="Most recent items first",
),
OpenApiExample(
name="Priority ascending",
value="priority",
description="Order by priority (urgent, high, medium, low, none)",
),
OpenApiExample(
name="State group",
value="state__group",
description="Order by state group (backlog, unstarted, started, completed, cancelled)", # noqa: E501
),
OpenApiExample(
name="Assignee name",
value="assignees__first_name",
description="Order by assignee first name",
),
],
)
# Search Parameters
SEARCH_PARAMETER = OpenApiParameter(
name="search",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Search query to filter results by name, description, or identifier",
required=False,
examples=[
OpenApiExample(
name="Name search",
value="bug fix",
description="Search for items containing 'bug fix'",
),
OpenApiExample(
name="Sequence ID",
value="123",
description="Search by sequence ID number",
),
],
)
SEARCH_PARAMETER_REQUIRED = OpenApiParameter(
name="search",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Search query to filter results by name, description, or identifier",
required=True,
examples=[
OpenApiExample(
name="Name search",
value="bug fix",
description="Search for items containing 'bug fix'",
),
OpenApiExample(
name="Sequence ID",
value="123",
description="Search by sequence ID number",
),
],
)
LIMIT_PARAMETER = OpenApiParameter(
name="limit",
type=OpenApiTypes.INT,
location=OpenApiParameter.QUERY,
description="Maximum number of results to return",
required=False,
examples=[
OpenApiExample(name="Default", value=10),
OpenApiExample(name="More results", value=50),
],
)
WORKSPACE_SEARCH_PARAMETER = OpenApiParameter(
name="workspace_search",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Whether to search across entire workspace or within specific project",
required=False,
examples=[
OpenApiExample(
name="Project only",
value="false",
description="Search within specific project only",
),
OpenApiExample(
name="Workspace wide",
value="true",
description="Search across entire workspace",
),
],
)
PROJECT_ID_QUERY_PARAMETER = OpenApiParameter(
name="project_id",
description="Project ID for filtering results within a specific project",
required=False,
type=OpenApiTypes.UUID,
location=OpenApiParameter.QUERY,
examples=[
OpenApiExample(
name="Example project ID",
value="550e8400-e29b-41d4-a716-446655440000",
description="Filter results for this project",
)
],
)
# Cycle View Parameter
CYCLE_VIEW_PARAMETER = OpenApiParameter(
name="cycle_view",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Filter cycles by status",
required=False,
examples=[
OpenApiExample(name="All cycles", value="all"),
OpenApiExample(name="Current cycles", value="current"),
OpenApiExample(name="Upcoming cycles", value="upcoming"),
OpenApiExample(name="Completed cycles", value="completed"),
OpenApiExample(name="Draft cycles", value="draft"),
OpenApiExample(name="Incomplete cycles", value="incomplete"),
],
)
# Field Selection Parameters
FIELDS_PARAMETER = OpenApiParameter(
name="fields",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Comma-separated list of fields to include in response",
required=False,
examples=[
OpenApiExample(
name="Basic fields",
value="id,name,description",
description="Include only basic fields",
),
OpenApiExample(
name="With relations",
value="id,name,assignees,state",
description="Include fields with relationships",
),
],
)
EXPAND_PARAMETER = OpenApiParameter(
name="expand",
type=OpenApiTypes.STR,
location=OpenApiParameter.QUERY,
description="Comma-separated list of related fields to expand in response",
required=False,
examples=[
OpenApiExample(
name="Expand assignees",
value="assignees",
description="Include full assignee details",
),
OpenApiExample(
name="Multiple expansions",
value="assignees,labels,state",
description="Include details for multiple relations",
),
],
)
ESTIMATE_ID_PARAMETER = OpenApiParameter(
name="estimate_id",
description="Estimate ID",
required=True,
type=OpenApiTypes.UUID,
location=OpenApiParameter.PATH,
)
plane-src/apps/api/plane/utils/openapi/responses.py
+490
View File
@@ -0,0 +1,490 @@
# Copyright (c) 2023-present Plane Software, Inc. and contributors
# SPDX-License-Identifier: AGPL-3.0-only
# See the LICENSE file for details.
"""
Common OpenAPI responses for drf-spectacular.
This module provides reusable response definitions for common HTTP status codes
and scenarios that occur across multiple API endpoints.
"""
from drf_spectacular.utils import OpenApiResponse, OpenApiExample, inline_serializer
from rest_framework import serializers
from .examples import get_sample_for_schema
# Authentication & Authorization Responses
UNAUTHORIZED_RESPONSE = OpenApiResponse(
description="Authentication credentials were not provided or are invalid.",
examples=[
OpenApiExample(
name="Unauthorized",
value={
"error": "Authentication credentials were not provided",
"error_code": "AUTHENTICATION_REQUIRED",
},
)
],
)
FORBIDDEN_RESPONSE = OpenApiResponse(
description="Permission denied. User lacks required permissions.",
examples=[
OpenApiExample(
name="Forbidden",
value={
"error": "You do not have permission to perform this action",
"error_code": "PERMISSION_DENIED",
},
)
],
)
# Resource Responses
NOT_FOUND_RESPONSE = OpenApiResponse(
description="The requested resource was not found.",
examples=[
OpenApiExample(
name="Not Found",
value={"error": "Not found", "error_code": "RESOURCE_NOT_FOUND"},
)
],
)
VALIDATION_ERROR_RESPONSE = OpenApiResponse(
description="Validation error occurred with the provided data.",
examples=[
OpenApiExample(
name="Validation Error",
value={
"error": "Validation failed",
"details": {"field_name": ["This field is required."]},
},
)
],
)
# Generic Success Responses
DELETED_RESPONSE = OpenApiResponse(
description="Resource deleted successfully",
examples=[
OpenApiExample(
name="Deleted Successfully",
value={"message": "Resource deleted successfully"},
)
],
)
ARCHIVED_RESPONSE = OpenApiResponse(
description="Resource archived successfully",
examples=[
OpenApiExample(
name="Archived Successfully",
value={"message": "Resource archived successfully"},
)
],
)
UNARCHIVED_RESPONSE = OpenApiResponse(
description="Resource unarchived successfully",
examples=[
OpenApiExample(
name="Unarchived Successfully",
value={"message": "Resource unarchived successfully"},
)
],
)
# Specific Error Responses
INVALID_REQUEST_RESPONSE = OpenApiResponse(
description="Invalid request data provided",
examples=[
OpenApiExample(
name="Invalid Request",
value={
"error": "Invalid request data",
"details": "Specific validation errors",
},
)
],
)
CONFLICT_RESPONSE = OpenApiResponse(
description="Resource conflict - duplicate or constraint violation",
examples=[
OpenApiExample(
name="Resource Conflict",
value={
"error": "Resource with the same identifier already exists",
"id": "550e8400-e29b-41d4-a716-446655440000",
},
)
],
)
ADMIN_ONLY_RESPONSE = OpenApiResponse(
description="Only admin or creator can perform this action",
examples=[
OpenApiExample(
name="Admin Only",
value={"error": "Only admin or creator can perform this action"},
)
],
)
CANNOT_DELETE_RESPONSE = OpenApiResponse(
description="Resource cannot be deleted due to constraints",
examples=[
OpenApiExample(
name="Cannot Delete",
value={"error": "Resource cannot be deleted", "reason": "Has dependencies"},
)
],
)
CANNOT_ARCHIVE_RESPONSE = OpenApiResponse(
description="Resource cannot be archived in current state",
examples=[
OpenApiExample(
name="Cannot Archive",
value={
"error": "Resource cannot be archived",
"reason": "Not in valid state",
},
)
],
)
REQUIRED_FIELDS_RESPONSE = OpenApiResponse(
description="Required fields are missing",
examples=[
OpenApiExample(
name="Required Fields Missing",
value={"error": "Required fields are missing", "fields": ["name", "type"]},
)
],
)
# Project-specific Responses
PROJECT_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Project not found",
examples=[
OpenApiExample(
name="Project Not Found",
value={"error": "Project not found"},
)
],
)
WORKSPACE_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Workspace not found",
examples=[
OpenApiExample(
name="Workspace Not Found",
value={"error": "Workspace not found"},
)
],
)
PROJECT_NAME_TAKEN_RESPONSE = OpenApiResponse(
description="Project name already taken",
examples=[
OpenApiExample(
name="Project Name Taken",
value={"error": "Project name already taken"},
)
],
)
# Issue-specific Responses
ISSUE_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Issue not found",
examples=[
OpenApiExample(
name="Issue Not Found",
value={"error": "Issue not found"},
)
],
)
WORK_ITEM_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Work item not found",
examples=[
OpenApiExample(
name="Work Item Not Found",
value={"error": "Work item not found"},
)
],
)
EXTERNAL_ID_EXISTS_RESPONSE = OpenApiResponse(
description="Resource with same external ID already exists",
examples=[
OpenApiExample(
name="External ID Exists",
value={
"error": "Resource with the same external id and external source already exists", # noqa: E501
"id": "550e8400-e29b-41d4-a716-446655440000",
},
)
],
)
# Label-specific Responses
LABEL_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Label not found",
examples=[
OpenApiExample(
name="Label Not Found",
value={"error": "Label not found"},
)
],
)
LABEL_NAME_EXISTS_RESPONSE = OpenApiResponse(
description="Label with the same name already exists",
examples=[
OpenApiExample(
name="Label Name Exists",
value={"error": "Label with the same name already exists in the project"},
)
],
)
# Module-specific Responses
MODULE_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Module not found",
examples=[
OpenApiExample(
name="Module Not Found",
value={"error": "Module not found"},
)
],
)
MODULE_ISSUE_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Module issue not found",
examples=[
OpenApiExample(
name="Module Issue Not Found",
value={"error": "Module issue not found"},
)
],
)
# Cycle-specific Responses
CYCLE_CANNOT_ARCHIVE_RESPONSE = OpenApiResponse(
description="Cycle cannot be archived",
examples=[
OpenApiExample(
name="Cycle Cannot Archive",
value={"error": "Only completed cycles can be archived"},
)
],
)
# State-specific Responses
STATE_NAME_EXISTS_RESPONSE = OpenApiResponse(
description="State with the same name already exists",
examples=[
OpenApiExample(
name="State Name Exists",
value={"error": "State with the same name already exists"},
)
],
)
STATE_CANNOT_DELETE_RESPONSE = OpenApiResponse(
description="State cannot be deleted",
examples=[
OpenApiExample(
name="State Cannot Delete",
value={
"error": "State cannot be deleted",
"reason": "Default state or has issues",
},
)
],
)
# Comment-specific Responses
COMMENT_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Comment not found",
examples=[
OpenApiExample(
name="Comment Not Found",
value={"error": "Comment not found"},
)
],
)
# Link-specific Responses
LINK_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Link not found",
examples=[
OpenApiExample(
name="Link Not Found",
value={"error": "Link not found"},
)
],
)
# Attachment-specific Responses
ATTACHMENT_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Attachment not found",
examples=[
OpenApiExample(
name="Attachment Not Found",
value={"error": "Attachment not found"},
)
],
)
# Search-specific Responses
BAD_SEARCH_REQUEST_RESPONSE = OpenApiResponse(
description="Bad request - invalid search parameters",
examples=[
OpenApiExample(
name="Bad Search Request",
value={"error": "Invalid search parameters"},
)
],
)
# Pagination Response Templates
def create_paginated_response(
item_schema,
schema_name,
description="Paginated results",
example_name="Paginated Response",
):
"""Create a paginated response with the specified item schema"""
return OpenApiResponse(
description=description,
response=inline_serializer(
name=schema_name,
fields={
"grouped_by": serializers.CharField(allow_null=True),
"sub_grouped_by": serializers.CharField(allow_null=True),
"total_count": serializers.IntegerField(),
"next_cursor": serializers.CharField(),
"prev_cursor": serializers.CharField(),
"next_page_results": serializers.BooleanField(),
"prev_page_results": serializers.BooleanField(),
"count": serializers.IntegerField(),
"total_pages": serializers.IntegerField(),
"total_results": serializers.IntegerField(),
"extra_stats": serializers.CharField(allow_null=True),
"results": serializers.ListField(child=item_schema()),
},
),
examples=[
OpenApiExample(
name=example_name,
value={
"grouped_by": "state",
"sub_grouped_by": "priority",
"total_count": 150,
"next_cursor": "20:1:0",
"prev_cursor": "20:0:0",
"next_page_results": True,
"prev_page_results": False,
"count": 20,
"total_pages": 8,
"total_results": 150,
"extra_stats": None,
"results": [get_sample_for_schema(schema_name)],
},
summary=example_name,
)
],
)
# Asset-specific Responses
PRESIGNED_URL_SUCCESS_RESPONSE = OpenApiResponse(description="Presigned URL generated successfully")
GENERIC_ASSET_UPLOAD_SUCCESS_RESPONSE = OpenApiResponse(
description="Presigned URL generated successfully",
examples=[
OpenApiExample(
name="Generic Asset Upload Response",
value={
"upload_data": {
"url": "https://s3.amazonaws.com/bucket-name",
"fields": {
"key": "workspace-id/uuid-filename.pdf",
"AWSAccessKeyId": "AKIA...",
"policy": "eyJ...",
"signature": "abc123...",
},
},
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"asset_url": "https://cdn.example.com/workspace-id/uuid-filename.pdf",
},
)
],
)
GENERIC_ASSET_VALIDATION_ERROR_RESPONSE = OpenApiResponse(
description="Validation error",
examples=[
OpenApiExample(
name="Missing required fields",
value={"error": "Name and size are required fields.", "status": False},
),
OpenApiExample(
name="Invalid file type",
value={"error": "Invalid file type.", "status": False},
),
],
)
ASSET_CONFLICT_RESPONSE = OpenApiResponse(
description="Asset with same external ID already exists",
examples=[
OpenApiExample(
name="Duplicate external asset",
value={
"message": "Asset with same external id and source already exists",
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"asset_url": "https://cdn.example.com/existing-file.pdf",
},
)
],
)
ASSET_DOWNLOAD_SUCCESS_RESPONSE = OpenApiResponse(
description="Presigned download URL generated successfully",
examples=[
OpenApiExample(
name="Asset Download Response",
value={
"asset_id": "550e8400-e29b-41d4-a716-446655440000",
"asset_url": "https://s3.amazonaws.com/bucket/file.pdf?signed-url",
"asset_name": "document.pdf",
"asset_type": "application/pdf",
},
)
],
)
ASSET_DOWNLOAD_ERROR_RESPONSE = OpenApiResponse(
description="Bad request",
examples=[
OpenApiExample(name="Asset not uploaded", value={"error": "Asset not yet uploaded"}),
],
)
ASSET_UPDATED_RESPONSE = OpenApiResponse(description="Asset updated successfully")
ASSET_DELETED_RESPONSE = OpenApiResponse(description="Asset deleted successfully")
ASSET_NOT_FOUND_RESPONSE = OpenApiResponse(
description="Asset not found",
examples=[OpenApiExample(name="Asset not found", value={"error": "Asset not found"})],
)