关于Swagger UI响应码显示不符的技术问询

Hey there! Let’s clear this up right away: this is not normal behavior. What you’re seeing is a mismatch between how your code handles error responses and how Swagger interprets them. Let’s break down why this happens and how to fix it.

Why You’re Seeing This Issue #

The core problem is that your code isn’t properly setting the HTTP response status code to 500. Instead, it’s returning a default 200 OK status and only tucking the error code into a response header. Swagger’s "Try it out" feature shows full response headers, so you can spot the custom error code there—but regular API consumers would only see the 200 status, which is confusing and breaks REST best practices.

Steps to Fix It #

1. Correctly Set the HTTP Status Code in Your Code

First, fix how your endpoint generates error responses. Stop hiding the error code in headers and explicitly set the HTTP status code to 500. Here are examples for common frameworks:

• Spring Boot:

  @GetMapping("/your-endpoint")
  public ResponseEntity<ErrorResponse> yourMethod() {
      // When an error occurs:
      ErrorResponse error = new ErrorResponse("Something went wrong");
      return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
  }
  

• Express.js:

  app.get('/your-endpoint', (req, res) => {
      // When an error occurs:
      res.status(500).json({ message: "Something went wrong" });
  });
  

2. Update Swagger Annotations to Document the 500 Response

Swagger might still show 200 OK as the default response unless you explicitly tell it to expect a 500. Use Swagger annotations to define valid responses for your endpoint:

• Springfox (Swagger 2):

  @ApiResponses(value = {
      @ApiResponse(code = 500, message = "Internal server error occurred", response = ErrorResponse.class),
      // Remove the 200 entry if your endpoint never returns a success state here
      // @ApiResponse(code = 200, message = "Success")
  })
  

• OpenAPI 3.0:

  @Operation(responses = {
      @ApiResponse(responseCode = "500", description = "Internal server error", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
  })
  

This tells Swagger to display only the 500 response in documentation, not the default 200.

3. Verify the Response with External Tools

Don’t rely solely on Swagger—test your endpoint with curl or Postman to confirm the status code is correctly set:

curl -v https://your-api-url/your-endpoint

Look for HTTP/1.1 500 Internal Server Error in the response headers to confirm it’s working.

4. Check for Global Exception Handlers

If you’re using a framework with global exception handling, make sure it’s not overriding your status code. For example, in Spring Boot, a misconfigured @RestControllerAdvice might catch exceptions and return 200 by default. Update it to return the correct 500 status:

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericException(Exception ex) {
        ErrorResponse error = new ErrorResponse(ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

Final Result #

Once you’ve made these changes, your endpoint will return a proper 500 status code, Swagger will display only that response in documentation, and the "Try it out" feature will show the correct status code instead of 200 OK.

内容的提问来源于stack exchange，提问作者dorcsi