Skip to content

refactor: move OpenApiParameter definitions to schema for better organization #4530

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
liuruibin merged 1 commit into from
Dec 17, 2025
Merged

refactor: move OpenApiParameter definitions to schema for better organization #4530

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 12 additions & 22 deletions apps/knowledge/api/document.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,28 +20,6 @@ def get_parameters():
location='path',
required=True,
),

OpenApiParameter(
name="limit",
description="分段长度",
type=OpenApiTypes.INT,
location='query',
required=False,
),
OpenApiParameter(
name="patterns",
description="分段正则列表",
type=OpenApiTypes.STR,
location='query',
required=False,
),
OpenApiParameter(
name="with_filter",
description="是否清除特殊字符",
type=OpenApiTypes.BOOL,
location='query',
required=False,
),
]

@staticmethod
Expand All @@ -53,6 +31,18 @@ def get_request():
'file': {
'type': 'string',
'format': 'binary' # Tells Swagger it's a file
},
'limit': {
'type': 'integer',
'description': '分段长度'
},
'patterns': {
'type': 'string',
'description': '分段正则列表'
},
'with_filter': {
'type': 'boolean',
'description': '是否清除特殊字符'
}
}
}
Copy link
Contributor Author

@shaohuzhang1 shaohuzhang1 Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Expand Down
Loading