323 lines
8.5 KiB
Python
323 lines
8.5 KiB
Python
# Copyright (c) 2023-present Plane Software, Inc. and contributors
|
|
# SPDX-License-Identifier: AGPL-3.0-only
|
|
# See the LICENSE file for details.
|
|
|
|
"""
|
|
OpenAPI utilities for drf-spectacular integration.
|
|
|
|
This module provides reusable components for API documentation:
|
|
- Authentication extensions
|
|
- Common parameters and responses
|
|
- Helper decorators
|
|
- Schema preprocessing hooks
|
|
- Examples
|
|
"""
|
|
|
|
# Authentication extensions
|
|
from .auth import APIKeyAuthenticationExtension
|
|
|
|
# Parameters
|
|
from .parameters import (
|
|
WORKSPACE_SLUG_PARAMETER,
|
|
PROJECT_ID_PARAMETER,
|
|
PROJECT_PK_PARAMETER,
|
|
PROJECT_IDENTIFIER_PARAMETER,
|
|
ISSUE_IDENTIFIER_PARAMETER,
|
|
ASSET_ID_PARAMETER,
|
|
CYCLE_ID_PARAMETER,
|
|
MODULE_ID_PARAMETER,
|
|
MODULE_PK_PARAMETER,
|
|
ISSUE_ID_PARAMETER,
|
|
STATE_ID_PARAMETER,
|
|
LABEL_ID_PARAMETER,
|
|
COMMENT_ID_PARAMETER,
|
|
LINK_ID_PARAMETER,
|
|
ATTACHMENT_ID_PARAMETER,
|
|
ACTIVITY_ID_PARAMETER,
|
|
CURSOR_PARAMETER,
|
|
PER_PAGE_PARAMETER,
|
|
EXTERNAL_ID_PARAMETER,
|
|
EXTERNAL_SOURCE_PARAMETER,
|
|
ORDER_BY_PARAMETER,
|
|
SEARCH_PARAMETER,
|
|
SEARCH_PARAMETER_REQUIRED,
|
|
LIMIT_PARAMETER,
|
|
WORKSPACE_SEARCH_PARAMETER,
|
|
PROJECT_ID_QUERY_PARAMETER,
|
|
CYCLE_VIEW_PARAMETER,
|
|
FIELDS_PARAMETER,
|
|
EXPAND_PARAMETER,
|
|
)
|
|
|
|
# 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,
|
|
STICKY_EXAMPLE,
|
|
)
|
|
|
|
# Helper decorators
|
|
from .decorators import (
|
|
workspace_docs,
|
|
project_docs,
|
|
issue_docs,
|
|
intake_docs,
|
|
asset_docs,
|
|
user_docs,
|
|
cycle_docs,
|
|
work_item_docs,
|
|
work_item_relation_docs,
|
|
label_docs,
|
|
issue_link_docs,
|
|
issue_comment_docs,
|
|
issue_activity_docs,
|
|
issue_attachment_docs,
|
|
module_docs,
|
|
module_issue_docs,
|
|
state_docs,
|
|
)
|
|
|
|
# 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",
|
|
"STICKY_EXAMPLE",
|
|
# Decorators
|
|
"workspace_docs",
|
|
"project_docs",
|
|
"issue_docs",
|
|
"intake_docs",
|
|
"asset_docs",
|
|
"user_docs",
|
|
"cycle_docs",
|
|
"work_item_docs",
|
|
"work_item_relation_docs",
|
|
"label_docs",
|
|
"issue_link_docs",
|
|
"issue_comment_docs",
|
|
"issue_activity_docs",
|
|
"issue_attachment_docs",
|
|
"module_docs",
|
|
"module_issue_docs",
|
|
"state_docs",
|
|
# Hooks
|
|
"preprocess_filter_api_v1_paths",
|
|
"generate_operation_summary",
|
|
]
|