add doc

[asukaminato0721]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

part of #24421

Screenshots

Before	After
...	...

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods

[Copilot]

Pull Request Overview

This PR refactors request parser definitions in several controller files by extracting them from within route handler methods to module-level scope and adding @api.expect() decorators to improve API documentation. The changes primarily affect plugin management, statistics, app management, and authentication endpoints.

Key Changes:

• Extracted request parsers from method-level to module-level scope
• Added @api.expect(parser) decorators to document API request schemas
• Added api import to files where needed
• Added missing language parameter documentation in setup endpoint

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
api/controllers/console/workspace/plugin.py	Extracted 18 request parsers to module scope and added @api.expect() decorators for plugin API endpoints
api/controllers/console/version.py	Moved version check parser to module scope and added @api.expect() decorator
api/controllers/console/setup.py	Added documentation for optional language parameter in setup API
api/controllers/console/datasets/rag_pipeline/datasource_auth.py	Extracted 7 datasource authentication parsers to module scope with @api.expect() decorators
api/controllers/console/app/statistic.py	Extracted shared statistics parser to module scope, reused across 7 endpoints
api/controllers/console/app/app_import.py	Moved app import parser to module scope and added @api.expect() decorator
api/controllers/console/app/app.py	Extracted app name parser to module scope and added @api.expect() decorator
api/controllers/console/app/annotation.py	Moved annotation update parser to module scope with @api.expect() decorator
api/controllers/console/app/agent.py	Extracted agent log parser to module scope and added @api.expect() decorator
api/controllers/console/app/advanced_prompt_template.py	Moved prompt template parser to module scope with @api.expect() decorator

Comments suppressed due to low confidence (1)

api/controllers/console/datasets/rag_pipeline/datasource_auth.py:1

• The variable name req is used inconsistently with parser used elsewhere in the file. Use consistent naming across all request parsers.

from flask import make_response, redirect, request

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors request parsers across multiple API controllers by moving them to the module level for reuse. This is a good practice that improves code clarity and performance. The changes also add @api.expect decorators, which enhances API documentation.

However, I've found a critical issue in api/controllers/console/datasets/rag_pipeline/datasource_auth.py and api/controllers/console/workspace/plugin.py where parser variable names (parser, req) are reused at the module level. This will lead to incorrect argument parsing for some endpoints as only the last definition will be effective.

Additionally, a minor regression was found where help texts for parser arguments were removed in one file, which reduces the clarity of the API documentation.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors request parsers in several controller files by moving them to the module level for reuse and adding @api.expect for Swagger documentation. While this is a good improvement for code clarity and maintainability, there is a critical issue in multiple files where parsers with the same name (parser, req, etc.) are defined at the module level. This causes later definitions to overwrite earlier ones, leading to incorrect request argument validation and parsing for most of the affected API endpoints. This needs to be fixed by giving each parser a unique name within its module.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request primarily refactors the code to move reqparse.RequestParser definitions to the module level. This is a positive change that improves performance and code clarity by avoiding parser re-creation on every request and reducing duplication. While the refactoring is generally well-executed, I've identified a critical issue in api/controllers/console/workspace/plugin.py where a parser variable req is redefined multiple times, which would lead to incorrect behavior. I've provided detailed comments and suggestions to fix this. Additionally, there's a minor performance improvement opportunity in api/controllers/console/workspace/account.py.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the code to define reqparse.RequestParser instances at the module level, which is a great improvement for performance and code clarity. It also adds @api.expect decorators, improving the API documentation.

The changes are well-executed across multiple files. I've found one minor inconsistency in api/controllers/console/workspace/account.py where a function is used to create a parser instead of a module-level variable, which I've commented on.

Please consider updating the pull request title and summary to better reflect the changes. A title like "Refactor: Move request parsers to module level and improve API docs" would be more descriptive.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request is a large-scale refactoring that significantly improves the code quality and API documentation. By moving reqparse.RequestParser definitions to the module level and using them with @api.expect, the code is now more consistent, readable, and maintainable. This change also fixes several inconsistencies where the API documentation did not match the actual implementation. The changes are well-executed across numerous files. This is an excellent contribution to the project's health. For future pull requests, I'd suggest a more descriptive title and a summary in the description to better reflect the changes made. For example, a title like "Refactor API request parsers for consistency and documentation" would be more informative. Overall, great work!

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request is a significant and valuable refactoring that moves reqparse.RequestParser definitions to the module level across numerous API controllers. This change greatly improves code clarity and maintainability by adhering to the DRY principle. It also fixes several inconsistencies between API documentation (@api.expect) and the actual argument parsing logic, which is a great improvement.

I've found a couple of minor typos in variable names and have a suggestion for making parser names more descriptive for better long-term maintainability. Overall, this is a solid and well-executed refactoring.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant and beneficial refactoring across numerous API controllers. By moving reqparse.RequestParser definitions to the module level and adding @api.expect decorators, the code is now more performant, organized, and better documented. This change also fixes several inconsistencies where the API documentation did not match the implementation. I've identified a couple of minor areas for improvement where argument handling could be simplified to rely on the parser's defaults, making the code clearer and more robust. Overall, this is a great improvement to the codebase.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request is a large-scale refactoring that moves reqparse.RequestParser definitions to the module level across numerous API controllers. This is a great improvement for code quality and maintainability, following the DRY principle by making parsers reusable and adding @api.expect decorators for better API documentation. The changes are consistent and well-executed. I've identified a couple of minor issues, primarily a potential unintended change in default parameter values and an opportunity to improve a parser's name for clarity.

[asukaminato0721]

/gemini review

[gemini-code-assist]

Code Review

This pull request is a significant and valuable refactoring effort. By moving the reqparse.RequestParser definitions to the module level and reusing them, you've greatly improved code reusability and maintainability, following the DRY principle. The addition of @api.expect decorators also enhances API documentation, which is a great plus. I've also noticed that this refactoring fixed a few inconsistencies and bugs, such as incorrect default values and redundant code. Overall, these changes improve the quality and clarity of the codebase. I have one suggestion for further consolidation in one of the files to reduce redundancy even more.

[asukaminato0721]

/gemini review