guanzhenxing opened a new pull request, #6049:
URL: https://github.com/apache/shenyu/pull/6049
# Add Swagger Import Functionality to ShenYu Admin
## Description
This PR adds a comprehensive Swagger document import functionality to ShenYu
Admin, allowing users to import API documentation from external Swagger/OpenAPI
endpoints directly into the ShenYu admin system.
## Features
### 🚀 New Features
- **Swagger Document Import**: Import API documentation from external
Swagger/OpenAPI endpoints
- **Multi-Version Support**: Full support for both Swagger 2.0 and OpenAPI
3.0 formats
- **Connection Testing**: Test connectivity to Swagger endpoints before
importing
- **URL Validation**: Comprehensive validation for Swagger URLs with proper
error handling
- **Document Parsing**: Enhanced SwaggerDocParser with version-aware parsing
capabilities
### 🔧 Technical Implementation
#### New Components Added:
1. **SwaggerImportController** - REST API endpoints for import operations
2. **SwaggerImportService** - Service interface for import logic
3. **SwaggerImportServiceImpl** - Implementation with HTTP client integration
4. **SwaggerImportRequest** - Request DTO with validation annotations
5. **SwaggerVersion** - Enumeration for version handling
6. **Enhanced SwaggerDocParser** - Updated to support both Swagger 2.0 and
OpenAPI 3.0
#### API Endpoints:
- `POST /swagger/import` - Import Swagger documentation
- `POST /swagger/test-connection` - Test connection to Swagger URL
## Code Changes
### Files Added:
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/SwaggerImportController.java`
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/model/dto/SwaggerImportRequest.java`
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/service/SwaggerImportService.java`
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java`
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/service/manager/impl/SwaggerVersion.java`
-
`shenyu-admin/src/test/java/org/apache/shenyu/admin/service/SwaggerImportServiceTest.java`
### Files Modified:
-
`shenyu-admin/src/main/java/org/apache/shenyu/admin/service/manager/impl/SwaggerDocParser.java`
- Added version detection logic
- Enhanced to support both Swagger 2.0 and OpenAPI 3.0 formats
- Refactored methods to accept version parameters
- Improved schema definition handling for different versions
## Version Support Details
### Swagger 2.0 Support:
- Schema definitions: `definitions` object
- Reference format: `#/definitions/ModelName`
- Response structure: `responses/200/schema`
### OpenAPI 3.0 Support:
- Schema definitions: `components/schemas` object
- Reference format: `#/components/schemas/ModelName`
- Response structure: `responses/200/content/application/json/schema`
## Testing
### Unit Tests:
- ✅ `SwaggerImportServiceTest` - Comprehensive test coverage for service
layer
- ✅ Input validation testing
- ✅ Error handling scenarios
- ✅ Connection testing functionality
### Manual Testing:
- ✅ Tested with real Swagger 2.0 endpoints
- ✅ Tested with real OpenAPI 3.0 endpoints
- ✅ Validated URL connection testing
- ✅ Confirmed proper error handling and validation
## Usage Example
### Import Swagger Documentation:
```bash
curl -X POST http://localhost:9095/swagger/import \
-H "Content-Type: application/json" \
-d '{
"swaggerUrl": "https://petstore.swagger.io/v2/swagger.json";,
"projectName": "petstore-api",
"projectDescription": "Pet Store API Documentation"
}'
```
### Test Connection:
```bash
curl -X POST http://localhost:9095/swagger/test-connection \
-H "Content-Type: application/json" \
-d "swaggerUrl=https://petstore.swagger.io/v2/swagger.json";
```
## Benefits
1. **Enhanced User Experience**: Users can now easily import existing
Swagger documentation
2. **Multi-Version Compatibility**: Supports both legacy Swagger 2.0 and
modern OpenAPI 3.0
3. **Robust Error Handling**: Comprehensive validation and error reporting
4. **Maintainable Code**: Clean architecture following ShenYu patterns
5. **Test Coverage**: Well-tested functionality with unit tests
## Backward Compatibility
- ✅ No breaking changes to existing APIs
- ✅ All existing SwaggerDocParser functionality preserved
- ✅ Enhanced capabilities are additive only
## Documentation
All code includes comprehensive JavaDoc documentation and follows ShenYu
coding standards.
## Checklist
- [x] Code follows ShenYu coding standards
- [x] Unit tests added and passing
- [x] Documentation updated
- [x] Backward compatibility maintained
- [x] Error handling implemented
- [x] Input validation added
- [x] Internationalization (English) applied
- [x] No breaking changes introduced
## Related Issues
This PR addresses the need for easier API documentation import capabilities
in ShenYu Admin, enabling users to leverage existing Swagger/OpenAPI
documentation.
---
**Type**: Feature
**Module**: admin
**Priority**: Medium
**Breaking Change**: No
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
