fix: file upload UI issues in Swagger documentation#16
Conversation
Add comprehensive content type resolution logic that properly handles browser inconsistencies when uploading markdown files. The system now checks both Content-Type headers and file extensions to determine the correct file type, ensuring reliable processing regardless of how the browser sends the multipart data. Key improvements: - Enhanced validateFile() method with canonical content type checking - New resolveContentType() method for intelligent type detection - Support for .md, .markdown, .txt, and .pdf file extensions - Fallback logic for generic content types like application/octet-stream This resolves Swagger UI file upload issues where markdown files were being rejected due to browser-specific Content-Type variations.
Improve Swagger UI documentation to better guide users through the file upload process. Added detailed explanations of supported file types, clarified Content-Type handling, and configured proper multipart form encoding specifications. Documentation improvements: - Expanded file type descriptions with extension examples - Added note about automatic Content-Type detection - Configured proper @encoding annotation for multipart forms - Refined parameter descriptions for better clarity - Updated RequestBody content specification These changes improve the developer experience when using the API documentation and testing file uploads through Swagger UI.
Remove trailing whitespace in search result parsing method to maintain consistent code formatting standards.
There was a problem hiding this comment.
Pull Request Overview
This PR fixes file upload issues in Swagger UI by implementing intelligent Content-Type resolution for file uploads. The changes address browser inconsistencies when uploading markdown files and improve API documentation clarity.
Key changes:
- Added intelligent Content-Type resolution that checks both HTTP headers and file extensions
- Enhanced file validation logic to use canonical content types
- Improved Swagger documentation with clearer descriptions and proper multipart encoding configuration
Reviewed Changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| FileStorageService.java | Implements content type resolution logic and updates file validation to handle browser inconsistencies |
| DocsSourceController.java | Updates Swagger annotations with better documentation and proper multipart encoding configuration |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| */ | ||
| private String getFileExtension(String filename) { | ||
| int lastDot = filename.lastIndexOf('.'); | ||
| if (lastDot == -1 || lastDot == filename.length() - 1) { |
There was a problem hiding this comment.
The condition lastDot == filename.length() - 1 will incorrectly return an empty string for files ending with a dot (e.g., 'file.'). This should return the empty string only when there's no extension, but a file ending with a dot should be handled differently or treated as having no valid extension.
| if (lastDot == -1 || lastDot == filename.length() - 1) { | |
| // No dot, or dot is the first character (dotfile), or dot is the last character (ends with dot) | |
| if (lastDot <= 0 || lastDot == filename.length() - 1) { |
| - Plain text files (text/plain, .txt files) | ||
|
|
||
| **Note:** The system automatically detects file types based on both the Content-Type header | ||
| and file extension. the system will properly recognize Markdown files regardless of how the browser sends the Content-Type. |
There was a problem hiding this comment.
Missing capitalization: 'the system' should be 'The system' as it starts a new sentence.
| and file extension. the system will properly recognize Markdown files regardless of how the browser sends the Content-Type. | |
| and file extension. The system will properly recognize Markdown files regardless of how the browser sends the Content-Type. |
| } | ||
|
|
||
| // Fallback to inbound or generic | ||
| return inbound != null ? inbound : "application/octet-stream"; |
There was a problem hiding this comment.
The fallback logic returns the original inbound content type for unknown extensions, which could bypass validation. Consider returning a specific unsupported type or logging this case, as it may allow unsupported file types to pass through if they have an unrecognized extension but valid inbound content type.
| return inbound != null ? inbound : "application/octet-stream"; | |
| default -> { | |
| log.warn("Unknown file extension '{}', treating as unsupported type. Inbound content type: '{}'", ext, inbound); | |
| yield "unsupported/unknown"; | |
| } | |
| }; | |
| } | |
| // Fallback to unsupported type if extension is missing | |
| log.warn("Unable to determine file extension for filename '{}', treating as unsupported type. Inbound content type: '{}'", filename, inbound); | |
| return "unsupported/unknown"; |
Summary
This PR resolves file upload issues in the Swagger UI where markdown files were being rejected due to inconsistent Content-Type handling betweenå different browsers.
The changes improve both the technical implementation and user documentation for file uploads.
Key Changes
Technical Implementation Notes
resolveContentType()method in FileStorageService to handle browser Content-Type variationsvalidateFile()method with canonical content type checkingapplication/octet-stream@RequestBodyconfiguration with proper encoding specificationsTesting Instructions
/swagger-ui.htmlin your browserPOST /api/v1/sources/upload)Files Modified
FileStorageService.java- Core file validation and type resolution logicDocsSourceController.java- API documentation improvementsSearchService.java- Minor formatting cleanupRelated Issues
Key Implementation Notes (1-Minute Report)
resolution
browsers