apache/shenyu · error · RuntimeException

Failed to get Swagger document, HTTP status code:

Error message

Failed to get Swagger document, HTTP status code:

What it means

fetchSwaggerDoc() throws RuntimeException when the HTTP GET against the configured swaggerUrl returns any status other than 200. The message includes the actual status code so the caller can tell whether the endpoint is missing (404), unauthorized (401/403), or server-side broken (5xx).

Solutions

Check the reported status code: 404 means wrong URL/path, 401/403 means auth is required, 5xx means backend failure.
curl the swaggerUrl from the admin server host to reproduce and inspect headers/body.
Correct the swaggerUrl to the actual docs endpoint (e.g. http://host:port/v3/api-docs).
Disable or satisfy auth requirements on the docs endpoint for the importing environment.

Example fix

// before
swaggerUrl: "http://localhost:8080/api-docs"   // 404
// after
swaggerUrl: "http://localhost:8080/v3/api-docs" // 200

Defensive patterns

Strategy: validation

Validate before calling

Response r = client.newCall(new Request.Builder().url(swaggerUrl).build()).execute();
if (r.code() != 200) throw new IllegalStateException("swagger endpoint returned " + r.code() + ", fix URL/auth before import");

Try / catch

try {
    service.importSwagger(request);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to get Swagger document, HTTP status code:")) {
        int code = Integer.parseInt(e.getMessage().replaceAll("\\D+", ""));
        // route by code: 404 -> fix URL, 401/403 -> fix auth, 5xx -> backend down
    }
    throw e;
}

Prevention

Verify the exact docs endpoint path (/v2/api-docs vs /v3/api-docs) per framework version.
Disable auth on docs endpoints in internal environments, or supply credentials to the importer.
Curl the URL from the admin host before configuring it.
Watch for redirects to login pages — they often yield 401/403 or HTML instead of JSON.

When it happens

Trigger: Swagger/MCP import with a swaggerUrl that responds non-200: wrong path, backend service not exposing /v2/api-docs or /v3/api-docs, missing auth, or a gateway/proxy returning an error page.

Common situations: Typo in the swagger URL; fetching an HTML login page instead of JSON (302 to login -> non-200 or wrong content); the backend app requires authentication for its docs endpoint; service is still starting and returns 503.

Related errors

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

Appendix: source

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

                return response.code() == 200;
            }
        } catch (Exception e) {
            LOG.warn("Failed to test Swagger URL connection: {}", swaggerUrl, e);
            return false;
        }
    }
    
    private void validateSwaggerUrl(final String swaggerUrl) {
        // Use UrlSecurityUtils for SSRF protection
        UrlSecurityUtils.validateUrlForSSRF(swaggerUrl);
    }
    
    private String fetchSwaggerDoc(final String swaggerUrl) throws IOException {
        try (Response response = httpUtils.requestForResponse(swaggerUrl,
                Collections.emptyMap(), Collections.emptyMap(), HttpUtils.HTTPMethod.GET, false)) {
            
            if (response.code() != 200) {
                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");

View on GitHub (pinned to 567142e072)