[type:feature] Add Swagger Import Functionality to ShenYu Admin #6050

guanzhenxing · 2025-07-09T07:35:44Z

What this PR does / why we need it

This PR adds a new Swagger import functionality to shenyu-admin, allowing users to import API documentation from Swagger 2.0 and OpenAPI 3.0 format URLs. This feature enables developers to quickly integrate existing API documentation into ShenYu gateway without manual configuration.

Types of changes

New feature (non-breaking change which adds functionality)

Changes in this PR

New Files Added:

SwaggerImportController.java - REST API controller with endpoints for import and connection testing
SwaggerImportService.java - Service interface for swagger import operations
SwaggerImportServiceImpl.java - Service implementation with URL validation and document parsing
SwaggerImportRequest.java - DTO model for swagger import requests
SwaggerVersion.java - Enumeration for swagger version detection
SwaggerImportServiceTest.java - Unit tests for the service layer

Modified Files:

SwaggerDocParser.java - Enhanced to support both Swagger 2.0 and OpenAPI 3.0 formats
- Added version detection logic
- Updated schema reference parsing for different versions
- Improved parameter and response handling

Key Features:

Multi-version Support: Supports both Swagger 2.0 (definitions) and OpenAPI 3.0 (components/schemas)
URL Validation: Validates HTTP/HTTPS URLs before processing
Connection Testing: Provides endpoint to test swagger URL connectivity
Error Handling: Comprehensive error handling with meaningful messages
Documentation Parsing: Automatically parses and stores API documentation
Internationalization: All messages and logs are in English

API Endpoints:

POST /swagger/import - Import swagger documentation from URL
POST /swagger/test-connection - Test connection to swagger URL

Testing

Manual Testing:

Start shenyu-admin application
Test swagger import with Swagger 2.0 format URL
Test swagger import with OpenAPI 3.0 format URL
Test connection validation with valid and invalid URLs
Verify error handling for malformed URLs and invalid swagger content

Unit Tests:

Added comprehensive unit tests for SwaggerImportServiceImpl
Tests cover URL validation, connection testing, and error scenarios
Mock-based testing for HTTP requests and DocManager interactions

Screenshots/Examples

Request Example:

{
  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
  "projectName": "petstore-api",
  "projectDescription": "Pet Store API Documentation"
}

Response Example:

{
  "code": 200,
  "message": "success",
  "data": "Import successful, supports Swagger 2.0 and OpenAPI 3.0 formats"
}

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules
I have followed the commit message format specified in the contributing guidelines

Additional Notes

This feature integrates seamlessly with the existing ShenYu admin architecture and follows the established patterns for service layer implementation. The swagger document parsing reuses the existing DocManager infrastructure, ensuring consistency with the current documentation management system.

The implementation is backward compatible and does not affect existing functionality. All new code follows ShenYu's coding standards and includes proper error handling and logging.

…wagger 2.0 and openapi 3.0. (cherry picked from commit 6cb0507)

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

- Add SwaggerVersion enum import in SwaggerDocParser - Update test case descriptions in SwaggerImportServiceTest - Move SwaggerVersion enum from the admin module to the common module

- Refactor the property handling logic in SwaggerDocParser to improve code readability and efficiency - Optimize HTTP request handling in SwaggerImportServiceImpl to enhance code flexibility - Remove unnecessary static HttpUtils instances to reduce resource consumption - Adjust code formatting and indentation to improve code cleanliness

- Use Objects.isNull() instead of direct equality checks to enhance code readability and safety - Improve the toString method of the SwaggerImportRequest class - Remove unused imports and optimize parts of the code structure

- Extract base path method to support Swagger 2.0 and OpenAPI 3.0 - Optimize HTTP request handling, use Spring Bean to manage HttpUtils - Improve log output, add document MD5 information - Refactor code structure to enhance maintainability and testability

Aias00 · 2025-07-11T01:35:18Z

hi, good job. any front pages?

Copilot

Pull Request Overview

This PR adds a Swagger import feature to ShenYu Admin, enabling users to import API definitions from Swagger 2.0 and OpenAPI 3.0 URLs.

New REST endpoints to import documentation and test connectivity
Service and parser support multi-version Swagger, URL validation, and error handling
DTOs, enums, and configuration for seamless integration with existing DocManager

Reviewed Changes

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

Show a summary per file

File	Description
shenyu-common/src/main/java/org/apache/shenyu/common/enums/SwaggerVersion.java	New enum to detect Swagger/OpenAPI versions
shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/SwaggerImportController.java	Adds `/import` and `/test-connection` endpoints
shenyu-admin/src/main/java/org/apache/shenyu/admin/service/SwaggerImportService.java	Declares import and connection test methods
shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java	Implements URL validation, fetching, content validation, and import
shenyu-admin/src/main/java/org/apache/shenyu/admin/service/manager/impl/SwaggerDocParser.java	Enhances parsing for V2/V3 schemas, base path and signals
shenyu-admin/src/main/java/org/apache/shenyu/admin/model/dto/SwaggerImportRequest.java	DTO with JSR-303 validation for import parameters
shenyu-admin/src/test/java/org/apache/shenyu/admin/service/SwaggerImportServiceTest.java	Unit tests for connection testing in the service layer
shenyu-admin/src/main/java/org/apache/shenyu/admin/config/HttpUtilsConfiguration.java	Registers HttpUtils as a Spring bean

Comments suppressed due to low confidence (2)

shenyu-admin/src/test/java/org/apache/shenyu/admin/service/SwaggerImportServiceTest.java:52

Add a test case for a successful connection scenario (e.g., mock HttpUtils to return a Response with code 200) to ensure testConnection returns true when expected.

        assertFalse(service.testConnection("http://invalid.example.com/swagger.json"));

shenyu-admin/src/main/java/org/apache/shenyu/admin/service/manager/impl/SwaggerDocParser.java:392

[nitpick] Add JavaDoc for private helper methods like extractBasePath, detectSwaggerVersion, and getSchemaDefinitions to clarify their behavior and inputs for future maintainers.

    private String extractBasePath(final JsonObject docRoot, final SwaggerVersion version) {

shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java

- Added UrlSecurityUtils utility class for URL security validation - Integrated URL security checks into the Swagger import feature - Implemented comprehensive validation for URL format, protocol, host, IP address, and port - Effectively prevents SSRF (Server-Side Request Forgery) and other URL-based attacks

guanzhenxing · 2025-07-11T09:13:31Z

hi, good job. any front pages?

I will complete the front-end pages in the next few days.

Aias00 · 2025-07-11T13:40:37Z

hi, good job. any front pages?

I will complete the front-end pages in the next few days.

this pr is ok, fix ci, waiting front together, ok?

- Update CSS file references in index.html - Update JavaScript file references in index.html

guanzhenxing · 2025-07-16T01:21:12Z

hi, good job. any front pages?

I will complete the front-end pages in the next few days.

this pr is ok, fix ci, waiting front together, ok?

Updated the front-end page

Aias00 · 2025-07-16T05:34:29Z

hi, add my wechat pls: aias00

Aias00 · 2025-07-16T09:46:57Z

@guanzhenxing hi, fix ci pls

…ty utility class - Optimized the code structure of the SwaggerImportServiceImpl class to improve code readability - Refactored the UrlSecurityUtils class to enhance URL security check functionality - Adjusted the exception handling method to make error messages clearer - Removed unused import statements to streamline the code

…henxing/shenyu into feature/import-swagger-url * 'feature/import-swagger-url' of https://github.com/guanzhenxing/shenyu: [type:feat] mcp server plugin (apache#5999)

* master: Bump org.apache.commons:commons-lang3 from 3.12.0 to 3.18.0 (apache#6052)

guanzhenxing · 2025-07-17T03:26:27Z

@guanzhenxing hi, fix ci pls

Already fixed them . This is ok or not ? @Aias00

guanzhenxing added 2 commits July 9, 2025 15:31

feature (admin) : add swagger import functionality with support for s…

9234c84

…wagger 2.0 and openapi 3.0. (cherry picked from commit 6cb0507)

Merge branch 'master' into feature/import-swagger-url

3cff6ca

Aias00 requested changes Jul 9, 2025

View reviewed changes

Aias00 added the admin: API Document label Jul 9, 2025

Aias00 requested a review from Copilot July 9, 2025 11:16

This comment was marked as outdated.

Sign in to view

guanzhenxing added 3 commits July 9, 2025 19:20

refactor(admin): Refactor Swagger-related code

73e6208

- Add SwaggerVersion enum import in SwaggerDocParser - Update test case descriptions in SwaggerImportServiceTest - Move SwaggerVersion enum from the admin module to the common module

refactor(admin): Optimize Swagger import-related code

c5e40d4

- Use Objects.isNull() instead of direct equality checks to enhance code readability and safety - Improve the toString method of the SwaggerImportRequest class - Remove unused imports and optimize parts of the code structure

Aias00 requested a review from Copilot July 10, 2025 01:23

This comment was marked as outdated.

Sign in to view

Aias00 requested a review from Copilot July 11, 2025 01:34

Copilot AI reviewed Jul 11, 2025

View reviewed changes

shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java Outdated Show resolved Hide resolved

shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java Outdated Show resolved Hide resolved

guanzhenxing mentioned this pull request Jul 16, 2025

feat(document): add swagger import functionality apache/shenyu-dashboard#535

Merged

feat(build): Update static resource version

b9f9bfe

- Update CSS file references in index.html - Update JavaScript file references in index.html

Merge branch 'master' into feature/import-swagger-url

f1a01d7

guanzhenxing added 3 commits July 16, 2025 22:47

Merge branch 'master' into feature/import-swagger-url

b7ee675

* master: Bump org.apache.commons:commons-lang3 from 3.12.0 to 3.18.0 (apache#6052)

Aias00 added 2 commits July 18, 2025 10:50

Merge branch 'master' into feature/import-swagger-url

08ca11c

Merge branch 'master' into feature/import-swagger-url

3668d0f

Aias00 approved these changes Jul 20, 2025

View reviewed changes

Aias00 merged commit aca751a into apache:master Jul 20, 2025
45 checks passed

Aias00 added this to the 2.7.0.2 milestone Jul 28, 2025

[type:feature] Add Swagger Import Functionality to ShenYu Admin #6050

[type:feature] Add Swagger Import Functionality to ShenYu Admin #6050

Uh oh!

Conversation

guanzhenxing commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it

Types of changes

Changes in this PR

New Files Added:

Modified Files:

Key Features:

API Endpoints:

Testing

Manual Testing:

Unit Tests:

Screenshots/Examples

Request Example:

Response Example:

Checklist

Additional Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Aias00 commented Jul 11, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

guanzhenxing commented Jul 11, 2025

Uh oh!

Aias00 commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

guanzhenxing commented Jul 16, 2025

Uh oh!

Aias00 commented Jul 16, 2025

Uh oh!

Aias00 commented Jul 16, 2025

Uh oh!

guanzhenxing commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

guanzhenxing commented Jul 9, 2025 •

edited

Loading

Aias00 commented Jul 11, 2025 •

edited

Loading

guanzhenxing commented Jul 17, 2025 •

edited

Loading