{"record":{"id":"f6b8c3deefea56f0","repo":"apache/shenyu","slug":"unsupported-swagger-version-only-swagger-2-0-and-openapi-3-0","errorCode":null,"errorMessage":"Unsupported Swagger version, only Swagger 2.0 and OpenAPI 3.0 formats are supported","messagePattern":"Unsupported Swagger version, only Swagger 2\\.0 and OpenAPI 3\\.0 formats are supported","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java","lineNumber":294,"sourceCode":"                throw new RuntimeException(\"Failed to get Swagger document, HTTP status code: \" + response.code());\n            }\n\n            return HttpUtils.readLimitedResponseBody(response.body(), maxSwaggerBodySize);\n        }\n    }\n\n\n\n    private void validateSwaggerContent(final String swaggerJson) {\n        try {\n            JsonObject docRoot = GsonUtils.getInstance().fromJson(swaggerJson, JsonObject.class);\n            \n            // Detect version\n            boolean isV2 = docRoot.has(\"swagger\") && docRoot.get(\"swagger\").getAsString().startsWith(\"2.\");\n            boolean isV3 = docRoot.has(\"openapi\") && docRoot.get(\"openapi\").getAsString().startsWith(\"3.\");\n            \n            if (!isV2 && !isV3) {\n                throw new IllegalArgumentException(\"Unsupported Swagger version, only Swagger 2.0 and OpenAPI 3.0 formats are supported\");\n            }\n            \n            LOG.info(\"Detected Swagger version: {}\", isV2 ? \"2.0\" : \"3.0\");\n            \n        } catch (Exception e) {\n            throw new IllegalArgumentException(\"Invalid Swagger JSON format: \" + e.getMessage());\n        }\n    }\n    \n    private UpstreamInstance createVirtualInstance(final SwaggerImportRequest request) {\n        UpstreamInstance instance = new UpstreamInstance();\n        instance.setContextPath(request.getProjectName());\n        \n        // Try to parse IP and port from URL\n        try {\n            URL url = new URL(request.getSwaggerUrl());\n            instance.setIp(url.getHost());\n            instance.setPort(url.getPort() == -1 ? (url.getProtocol().equals(\"https\") ? 443 : 80) : url.getPort());","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java#L276-L312","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the fetched URL actually serves a swagger/openapi document (check the root JSON for a version field).","Add or fix the version field: \"swagger\": \"2.0\" or \"openapi\": \"3.0.x\".","Convert non-swagger formats (Postman, RAML, API Blueprint) to OpenAPI 3.0 before importing.","If using OpenAPI 3.1, downgrade the version string to 3.0.x or convert the spec."],"exampleFix":"// before\n{ \"info\": { \"title\": \"api\" }, \"paths\": { ... } }          // no version field\n// after\n{ \"openapi\": \"3.0.1\", \"info\": { \"title\": \"api\" }, \"paths\": { ... } }","handlingStrategy":"validation","validationCode":"JsonObject root = JsonParser.parseString(swaggerJson).getAsJsonObject();\nboolean ok = (root.has(\"swagger\") && root.get(\"swagger\").getAsString().startsWith(\"2.\"))\n          || (root.has(\"openapi\") && root.get(\"openapi\").getAsString().startsWith(\"3.\"));\nif (!ok) throw new IllegalArgumentException(\"document must declare swagger 2.x or openapi 3.x\");","typeGuard":"boolean isSupportedSwagger(JsonObject root) {\n    return (root.has(\"swagger\") && root.get(\"swagger\").getAsString().startsWith(\"2.\"))\n        || (root.has(\"openapi\") && root.get(\"openapi\").getAsString().startsWith(\"3.\"));\n}","tryCatchPattern":"try {\n    service.importSwagger(request);\n} catch (IllegalArgumentException e) {\n    return ResponseEntity.badRequest().body(e.getMessage());\n}","preventionTips":["Check the spec's version field before pointing the importer at any URL.","Avoid OpenAPI 3.1+ version strings until the importer supports them (startsWith(\"3.\") check).","Never upload Postman/RAML exports directly; convert to OpenAPI 3.0 first.","Add spec linting (e.g. Spectral) in CI to enforce version fields."],"tags":["openapi","validation","version","swagger"],"backgroundTag":"invalid-argument-value","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}