base

2026-04-18 18:39:25 +03:00
commit 3ba092b60c
4944 changed files with 497564 additions and 0 deletions
@@ -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