bb-plane-fork/apps/api/plane/utils/openapi

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)

from plane.utils.openapi import (
    asset_docs,
    ASSET_ID_PARAMETER,
    UNAUTHORIZED_RESPONSE,
    # ... other imports
)

Import from Specific Modules (Recommended for new code)

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