Return code "default" causes issues with server stubs generators

[alexgordtop]

What?

The "default" return code, that is used in the swagger api to document the default error response, leads to wrong server stub generation in spring and other frameworks:

@Operation(summary = "Deletes an Asset Administration Shell Descriptor, i.e. de-registers an AAS", description = "", tags={ "Asset Administration Shell Registry API" })
    @ApiResponses(value = { 
        @ApiResponse(responseCode = "204", description = "Asset Administration Shell Descriptor deleted successfully"),

        @ApiResponse(responseCode = "400", description = "Bad Request, e.g. the request parameters of the format of the request body is wrong.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "404", description = "Not Found", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "500", description = "Internal Server Error", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "200", description = "Default error handling for unmentioned status codes", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))) })
    @RequestMapping(value = "/shell-descriptors/{aasIdentifier}",
        produces = { "application/json" }, 
        method = RequestMethod.DELETE)
    ResponseEntity<Void> deleteAssetAdministrationShellDescriptorById(@Parameter(in = ParameterIn.PATH, description = "The Asset Administration Shell’s unique id (UTF8-BASE64-URL-encoded)", required=true, schema=@Schema()) @PathVariable("aasIdentifier") byte[] aasIdentifier);

The default is usually interpreted as default successful response. For code generation, the default response defines the return type of the generated method - while the error codes are handled via custom exceptions.

How?

Remove the "default" response. When 400 is documented, 403 would usually be accepted with the same response type. There are ways to check for "client" oder "server" errors.

https://github.com/spring-projects/spring-framework/blob/main/spring-web/src/main/java/org/springframework/http/HttpStatus.java#L483

[alexgordtop]

Another example, where the default response leads to a ambiguous generation result:

-> responseCode 200 is contained with two different schemas...

 @Operation(summary = "Returns all Asset Administration Shell Descriptors", description = "", tags={ "Asset Administration Shell Registry API" })
    @ApiResponses(value = { 
        @ApiResponse(responseCode = "200", description = "Requested Asset Administration Shell Descriptors", content = @Content(mediaType = "application/json", schema = @Schema(implementation = GetAssetAdministrationShellDescriptorsResult.class))),

        @ApiResponse(responseCode = "400", description = "Bad Request, e.g. the request parameters of the format of the request body is wrong.", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "403", description = "Forbidden", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "500", description = "Internal Server Error", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))),

        @ApiResponse(responseCode = "200", description = "Default error handling for unmentioned status codes", content = @Content(mediaType = "application/json", schema = @Schema(implementation = Result.class))) })
    @RequestMapping(value = "/shell-descriptors",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    ResponseEntity<GetAssetAdministrationShellDescriptorsResult> getAllAssetAdministrationShellDescriptors(....);