vignesh/jira
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
jira/apps/api/plane/utils/openapi/__init__.py

316 lines
8.3 KiB
Python
Raw Normal View History

[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-24 18:47:05 +00:00
"""
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",
]
Reference in a new issue Copy permalink