apache/shenyu · error · IllegalArgumentException

Unsupported Swagger version, only Swagger 2.0 and OpenAPI…

Error message

Unsupported Swagger version, only Swagger 2.0 and OpenAPI 3.0 formats are supported

What it means

validateSwaggerContent() throws IllegalArgumentException when the fetched JSON parses but contains neither a `swagger` field starting with "2." nor an `openapi` field starting with "3.". Only Swagger 2.0 and OpenAPI 3.x documents are supported by the import pipeline; anything else (e.g. Postman collections, RAML exports, HTML) is rejected as bad user input.

Solutions

1. Verify the fetched URL actually serves a swagger/openapi document (check the root JSON for a version field).
2. Add or fix the version field: "swagger": "2.0" or "openapi": "3.0.x".
3. Convert non-swagger formats (Postman, RAML, API Blueprint) to OpenAPI 3.0 before importing.
4. If using OpenAPI 3.1, downgrade the version string to 3.0.x or convert the spec.

Example fix

// before
{ "info": { "title": "api" }, "paths": { ... } }          // no version field
// after
{ "openapi": "3.0.1", "info": { "title": "api" }, "paths": { ... } }

JsonObject root = JsonParser.parseString(swaggerJson).getAsJsonObject();
boolean ok = (root.has("swagger") && root.get("swagger").getAsString().startsWith("2."))
          || (root.has("openapi") && root.get("openapi").getAsString().startsWith("3."));
if (!ok) throw new IllegalArgumentException("document must declare swagger 2.x or openapi 3.x");

boolean isSupportedSwagger(JsonObject root) {
    return (root.has("swagger") && root.get("swagger").getAsString().startsWith("2."))
        || (root.has("openapi") && root.get("openapi").getAsString().startsWith("3."));
}

try {
    service.importSwagger(request);
} catch (IllegalArgumentException e) {
    return ResponseEntity.badRequest().body(e.getMessage());
}

When it happens

Trigger: Importing a document whose root JSON has no recognized version field: a random JSON file, an API-spec in another format, or an OpenAPI document with a malformed version string (e.g. "openapi": "4.0" or missing version).

Common situations: Pointing the importer at a non-swagger JSON endpoint (health endpoint, config endpoint); exporting specs from tools that omit the version field; trying OpenAPI 3.1+ which fails the startsWith("3.") check; uploading HTML saved as .json.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• OpenAPI document is missing the top-level 'servers' field…
• Invalid Swagger JSON format:
• OpenAPI pathKey cannot be null or empty
• OpenAPI methodType cannot be null or empty
• namespaceId is null

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/f6b8c3deefea56f0. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java:294

                throw new RuntimeException("Failed to get Swagger document, HTTP status code: " + response.code());
            }

            return HttpUtils.readLimitedResponseBody(response.body(), maxSwaggerBodySize);
        }
    }



    private void validateSwaggerContent(final String swaggerJson) {
        try {
            JsonObject docRoot = GsonUtils.getInstance().fromJson(swaggerJson, JsonObject.class);
            
            // Detect version
            boolean isV2 = docRoot.has("swagger") && docRoot.get("swagger").getAsString().startsWith("2.");
            boolean isV3 = docRoot.has("openapi") && docRoot.get("openapi").getAsString().startsWith("3.");
            
            if (!isV2 && !isV3) {
                throw new IllegalArgumentException("Unsupported Swagger version, only Swagger 2.0 and OpenAPI 3.0 formats are supported");
            }
            
            LOG.info("Detected Swagger version: {}", isV2 ? "2.0" : "3.0");
            
        } catch (Exception e) {
            throw new IllegalArgumentException("Invalid Swagger JSON format: " + e.getMessage());
        }
    }
    
    private UpstreamInstance createVirtualInstance(final SwaggerImportRequest request) {
        UpstreamInstance instance = new UpstreamInstance();
        instance.setContextPath(request.getProjectName());
        
        // Try to parse IP and port from URL
        try {
            URL url = new URL(request.getSwaggerUrl());
            instance.setIp(url.getHost());
            instance.setPort(url.getPort() == -1 ? (url.getProtocol().equals("https") ? 443 : 80) : url.getPort());

View on GitHub (pinned to 567142e072)