refactor: move OpenApiParameter definitions to schema for better organization

[shaohuzhang1]

refactor: move OpenApiParameter definitions to schema for better organization --bug=1064802 --user=刘瑞斌 【接口文档】/admin/api/workspace/{workspace_id}/knowledge/{knowledge_id}/document/split 接口的参数传递方式错了 https://www.tapd.cn/62980211/s/1813972

[f2c-ci-robot]

Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[f2c-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[shaohuzhang1]

The provided code snippets appear to be part of an OpenAPI specification for an API endpoint in Python. The changes you've made are primarily related to removing redundant parameters that were previously defined but have been omitted due to comments or potential removal in further development. Here are some recommendations:

1. Remove the commented-out parameters: You should consider deleting these unused parameters from your specifications if they are no longer needed or intended to be included.

2. Consistent naming and description conventions: Ensure consistent use of parameter names and descriptions throughout your documentation. This can help maintain clarity and reduce errors when interpreting the specifications.

3. Document optional vs required parameters: Clearly indicate which parameters are optional and which are mandatory in your definitions, especially for more complex endpoints where this is relevant.

4. Validation rules: If using a tool like Swagger UI, ensure that validation rules (like data types) are correctly specified for each parameter. Incorrectly typed parameters could lead to runtime issues or confusion with other tools.

Here’s a revised version of the get_parameters method that includes only necessary parameters and maintains consistency:

def get_parameters():
    return [
        OpenApiParameter(
            name="location",
            description="数据文件路径",
            type=OpenApiTypes.STRING,
            location='query',
            required=True,
        ),
        OpenApiParameter(
            name="limit",
            description="分段长度（可选）",
            type = OpenApiTypes.INTEGER,
            location='query',
            required=False,
        ),
        OpenApiParameter(
            name="patterns",
            description="分段正则列表（可选）",
            type = OpenApiTypes.STRING,
            location='query',
            required=False,
        ),
        OpenApiParameter(
            name="with_filter",
            description="是否清除特殊字符（可选项）",
            type=OpenApiTypes.BOOL,
            location='query',
            required=False,
        ),
    ]

In addition, you might want to update the request body definition for handling files differently or add additional validations as per project requirements:

class MyModel(BaseModel):
    my_field_1: str  # Add appropriate field definitions based on your needs

@app.post("/endpoint")
async def handle_input(file: UploadFile = File(...), input_data: Optional[MyModel] = None,...):
    # Your implementation here ...

And finally, make sure to update the request schema accordingly when using this new structure:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          my_file:
            format: binary
          limit:
            type: integer
          patterns:
            type: string
          with_filter:
            type: boolean
        required:
          - my_file