[WEB-4045] feat: restructuring of the external APIs for better maintainability (#7477)

* Basic setup for drf-spectacular * Updated to only handle /api/v1 endpoints * feat: add asset and user endpoints with URL routing - Introduced new asset-related endpoints for user assets and server assets, allowing for asset uploads and management. - Added user endpoint to retrieve current user information. - Updated URL routing to include new asset and user patterns. - Enhanced issue handling with a new search endpoint for issues across multiple fields. - Expanded member management with a new endpoint for workspace members. * Group endpoints by tags * Detailed schema definitions and examples for asset endpoints * Removed unnecessary extension * Specify avatar_url field separately * chore: add project docs * chore: correct all errors * chore: added open spec in work items * feat: enhance cycle API endpoints with detailed OpenAPI specifications - Updated CycleAPIEndpoint and CycleIssueAPIEndpoint to include detailed OpenAPI schema definitions for GET, POST, PATCH, and DELETE operations. - Specified allowed HTTP methods for each endpoint in the URL routing. - Improved documentation for cycle creation, updating, and deletion, including request and response examples. * chore: added open spec in labels * chore: work item properties * feat: enhance API endpoints with OpenAPI specifications and HTTP method definitions - Added detailed OpenAPI schema definitions for various API endpoints including Intake, Module, and State. - Specified allowed HTTP methods for each endpoint in the URL routing for better clarity and documentation. - Improved request and response examples for better understanding of API usage. - Introduced unarchive functionality for cycles and modules with appropriate endpoint definitions. * chore: run formatter * Removed unnecessary settings for authentication * Refactors OpenAPI documentation structure Improves the organization and maintainability of the OpenAPI documentation by modularizing the `openapi_spec_helpers.py` file. The changes include: - Migrates common parameters, responses, examples, and authentication extensions to separate modules. - Introduces helper decorators for different endpoint types. - Updates view imports to use the new module paths. - Removes the legacy `openapi_spec_helpers.py` file. This refactoring results in a more structured and easier-to-maintain OpenAPI documentation setup. * Refactor OpenAPI endpoint specifications - Removed unnecessary parameters from the OpenAPI documentation for various endpoints in the asset, cycle, and project views. - Updated request structures to improve clarity and consistency across the API documentation. - Enhanced response formatting for better readability and maintainability. * Enhance API documentation with detailed endpoint descriptions Updated various API endpoints across the application to include comprehensive docstrings that clarify their functionality. Each endpoint now features a summary and detailed description, improving the overall understanding of their purpose and usage. This change enhances the OpenAPI specifications for better developer experience and documentation clarity. * Enhance API serializers and views with new request structures - Added new serializers for handling cycle and module issue requests, including `CycleIssueRequestSerializer`, `TransferCycleIssueRequestSerializer`, `ModuleIssueRequestSerializer`, and intake issue creation/updating serializers. - Updated existing serializers to improve clarity and maintainability, including the `UserAssetUploadSerializer` and `IssueAttachmentUploadSerializer`. - Refactored API views to utilize the new serializers, enhancing the request handling for cycle and intake issue endpoints. - Improved OpenAPI documentation by replacing inline request definitions with serializer references for better consistency and readability. * Refactor OpenAPI documentation and endpoint specifications - Replaced inline schema definitions with dedicated decorators for various endpoint types, enhancing clarity and maintainability. - Updated API views to utilize new decorators for user, cycle, intake, module, and project endpoints, improving consistency in OpenAPI documentation. - Removed unnecessary parameters and responses from endpoint specifications, streamlining the documentation for better readability. - Enhanced the organization of OpenAPI documentation by modularizing endpoint-specific decorators and parameters. * chore: correct formatting * chore: correct formatting for all api folder files * refactor: clean up serializer imports and test setup - Removed unused `StateLiteSerializer` import from the serializer module. - Updated test setup to include a noqa comment for the `django_db_setup` fixture, ensuring clarity in the code. - Added missing commas in user data dictionary for consistency. * feat: add project creation and update serializers with validation - Introduced `ProjectCreateSerializer` and `ProjectUpdateSerializer` to handle project creation and updates, respectively. - Implemented validation to ensure project leads and default assignees are members of the workspace. - Updated API views to utilize the new serializers for creating and updating projects, enhancing request handling. - Added OpenAPI documentation references for the new serializers in the project API endpoints. * feat: update serializers to include additional read-only fields * refactor: rename intake issue serializers and enhance structure - Renamed `CreateIntakeIssueRequestSerializer` to `IntakeIssueCreateSerializer` and `UpdateIntakeIssueRequestSerializer` to `IntakeIssueUpdateSerializer` for clarity. - Introduced `IssueSerializer` for nested issue data in intake requests, improving the organization of serializer logic. - Updated API views to utilize the new serializer names, ensuring consistency across the codebase. * refactor: rename issue serializer for intake and enhance API documentation - Renamed `IssueSerializer` to `IssueForIntakeSerializer` for better clarity in the context of intake issues. - Updated references in `IntakeIssueCreateSerializer` and `IntakeIssueUpdateSerializer` to use the new `IssueForIntakeSerializer`. - Added OpenAPI documentation for the `get_workspace_work_item` endpoint, detailing parameters and responses for improved clarity. * chore: modules and cycles serializers * feat: add new serializers for label and issue link management - Introduced `LabelCreateUpdateSerializer`, `IssueLinkCreateSerializer`, `IssueLinkUpdateSerializer`, and `IssueCommentCreateSerializer` to enhance the handling of label and issue link data. - Updated existing API views to utilize the new serializers for creating and updating labels, issue links, and comments, improving request handling and validation. - Added `IssueSearchSerializer` for searching issues, streamlining the search functionality in the API. * Don't consider read only fields as required * Add setting to separate request and response definitions * Fixed avatar_url warning on openapi spec generation * Made spectacular disabled by default * Moved spectacular settings into separate file and added detailed descriptions to tags * Specify methods for asset urls * Better server names * Enhance API documentation with summaries for various endpoints - Added summary descriptions for user asset, cycle, intake, issue, member, module, project, state, and user API endpoints to improve clarity and usability of the API documentation. - Updated the OpenAPI specifications to reflect these changes, ensuring better understanding for developers interacting with the API. * Add contact information to OpenAPI settings - Included contact details for Plane in the OpenAPI settings to enhance API documentation and provide developers with a direct point of contact for support. - This addition aims to improve the overall usability and accessibility of the API documentation. * Reordered tags and improved description relavancy * Enhance OpenAPI documentation for cycle and issue endpoints - Added response definitions for the `get_cycle_issues` and `delete_cycle_issue` methods in the CycleIssueAPIEndpoint to clarify expected outcomes. - Included additional response codes for the IssueSearchEndpoint to handle various error scenarios, improving the overall API documentation and usability. * Enhance serializer documentation across multiple files - Updated docstrings for various serializers including UserAssetUploadSerializer, AssetUpdateSerializer, and others to provide clearer descriptions of their functionality and usage. - Improved consistency in formatting and language across serializer classes to enhance readability and maintainability. - Added detailed explanations for new serializers related to project, module, and cycle management, ensuring comprehensive documentation for developers. * Refactor API endpoints for cycles, intake, modules, projects, and states - Replaced existing API endpoint classes with more descriptive names such as CycleListCreateAPIEndpoint, CycleDetailAPIEndpoint, IntakeIssueListCreateAPIEndpoint, and others to enhance clarity. - Updated URL patterns to reflect the new endpoint names, ensuring consistency across the API. - Improved documentation and method summaries for better understanding of endpoint functionalities. - Enhanced query handling in the new endpoint classes to streamline data retrieval and improve performance. * Refactor issue and label API endpoints for clarity and functionality - Renamed existing API endpoint classes to more descriptive names such as IssueListCreateAPIEndpoint, IssueDetailAPIEndpoint, LabelListCreateAPIEndpoint, and LabelDetailAPIEndpoint to enhance clarity. - Updated URL patterns to reflect the new endpoint names, ensuring consistency across the API. - Improved method summaries and documentation for better understanding of endpoint functionalities. - Streamlined query handling in the new endpoint classes to enhance data retrieval and performance. * Refactor asset API endpoint methods and introduce new status enums - Updated the GenericAssetEndpoint to only allow POST requests for asset creation, removing the GET method. - Modified the get method to require asset_id, ensuring that asset retrieval is always tied to a specific asset. - Added new IntakeIssueStatus and ModuleStatus enums to improve clarity and management of asset and module states. - Enhanced OpenAPI settings to include these new enums for better documentation and usability. * enforce naming convention * Added LICENSE to openapi spec * Enhance OpenAPI documentation for various API endpoints - Updated API endpoints in asset, cycle, intake, issue, module, project, and state views to include OpenApiRequest and OpenApiExample for better request documentation. - Added example requests for creating and updating resources, improving clarity for API consumers. - Ensured consistent use of OpenApi utilities across all relevant endpoints to enhance overall API documentation quality. * Enhance OpenAPI documentation for various API endpoints - Added detailed descriptions to multiple API endpoints across asset, cycle, intake, issue, module, project, state, and user views to improve clarity for API consumers. - Ensured consistent documentation practices by including descriptions that outline the purpose and functionality of each endpoint. - This update aims to enhance the overall usability and understanding of the API documentation. * Update OpenAPI examples and enhance project queryset logic - Changed example fields in OpenAPI documentation for issue comments from "content" to "comment_html" to reflect the correct structure. - Introduced a new `get_queryset` method in the ProjectDetailAPIEndpoint to filter projects based on user membership and workspace, while also annotating additional project-related data such as total members, cycles, and modules. - Updated permission checks to use the correct attribute name for project identifiers, ensuring accurate permission handling. * Enhance OpenAPI documentation and add response examples - Updated multiple API endpoints across asset, cycle, intake, issue, module, project, state, and user views to include new OpenApiResponse examples for better clarity on expected outcomes. - Introduced new parameters for project and issue identifiers to improve request handling and documentation consistency. - Enhanced existing responses with detailed examples to aid API consumers in understanding the expected data structure and error handling. - This update aims to improve the overall usability and clarity of the API documentation. * refactor: update terminology from 'issues' to 'work items' across multiple API endpoints for consistency and clarity * use common timezones from pytz for choices * Moved the openapi utils to the new folder structure * Added exception logging in GenericAssetEndpoint to improve error handling * Fixed code rabbit suggestions * Refactored IssueDetailAPIEndpoint to streamline issue retrieval and response handling, removing redundant external ID checks and custom ordering logic. --------- Co-authored-by: pablohashescobar <nikhilschacko@gmail.com> Co-authored-by: NarayanBavisetti <narayan3119@gmail.com>
2025-07-25 00:17:05 +05:30 · 2025-07-25 00:17:05 +05:30 · 514686d9d5
commit 514686d9d5
parent 98a00f5bde
64 changed files with 7800 additions and 668 deletions
--- a/apps/api/plane/utils/openapi/README.md
+++ b/apps/api/plane/utils/openapi/README.md
@ -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 
--- a/apps/api/plane/utils/openapi/init.py
+++ b/apps/api/plane/utils/openapi/init.py
@ -0,0 +1,315 @@
+"""
+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,
+)
+
+# 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,
+    # 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,
+)
+
+# Helper decorators
+from .decorators import (
+    workspace_docs,
+    project_docs,
+    issue_docs,
+    intake_docs,
+    asset_docs,
+    user_docs,
+    cycle_docs,
+    work_item_docs,
+    label_docs,
+    issue_link_docs,
+    issue_comment_docs,
+    issue_activity_docs,
+    issue_attachment_docs,
+    module_docs,
+    module_issue_docs,
+    state_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",
+    # 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",
+    # 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",
+    # Decorators
+    "workspace_docs",
+    "project_docs",
+    "issue_docs",
+    "intake_docs",
+    "asset_docs",
+    "user_docs",
+    "cycle_docs",
+    "work_item_docs",
+    "label_docs",
+    "issue_link_docs",
+    "issue_comment_docs",
+    "issue_activity_docs",
+    "issue_attachment_docs",
+    "module_docs",
+    "module_issue_docs",
+    "state_docs",
+    # Hooks
+    "preprocess_filter_api_v1_paths",
+    "generate_operation_summary",
+]
--- a/apps/api/plane/utils/openapi/auth.py
+++ b/apps/api/plane/utils/openapi/auth.py
@ -0,0 +1,29 @@
+"""
+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.",
+        }
--- a/apps/api/plane/utils/openapi/decorators.py
+++ b/apps/api/plane/utils/openapi/decorators.py
@ -0,0 +1,264 @@
+"""
+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 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))
--- a/apps/api/plane/utils/openapi/examples.py
+++ b/apps/api/plane/utils/openapi/examples.py
@ -0,0 +1,816 @@
+"""
+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>",
+        "comment_json": {
+            "type": "doc",
+            "content": [
+                {
+                    "type": "paragraph",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "This issue has been resolved by implementing OAuth 2.0 flow.",
+                        }
+                    ],
+                }
+            ],
+        },
+        "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",
+)
+
+# 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",
+    },
+)
+
+
+# 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>",
+    "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",
+}
+
+# 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,
+}
+
+
+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)
--- a/apps/api/plane/utils/openapi/hooks.py
+++ b/apps/api/plane/utils/openapi/hooks.py
@ -0,0 +1,56 @@
+"""
+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}")
--- a/apps/api/plane/utils/openapi/parameters.py
+++ b/apps/api/plane/utils/openapi/parameters.py
@ -0,0 +1,493 @@
+"""
+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)",
+        ),
+        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",
+        ),
+    ],
+)
--- a/apps/api/plane/utils/openapi/responses.py
+++ b/apps/api/plane/utils/openapi/responses.py
@ -0,0 +1,492 @@
+"""
+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",
+                "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"})
+    ],
+)