swagger-api / swagger-api/swagger-codegen

[jaxrs] WebApplicationException to handle error response codes

Open
#7,315 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

Description

as already mentioned here by @Tillerino,

a much cleaner way of handling response codes in JAX-RS is using WebApplicationException

This way, the service implementation can exploit the marshalling for DTO classes.
For example, instead of:

@Override
public Response getMyExamples(SecurityContext securityContext) throws NotFoundException {
        // do some magic!
        return Response.ok().entity(new ApiResponseMessage(ApiResponseMessage.OK, "magic!")).build();
}

we can generate:

@Override
public List<MyExample> getMyExamples(SecurityContext securityContext) 
       throws  javax.ws.rs.WebApplicationException {
        // TODO do some magic! 
        throw new InternalServerErrorException("Not yet Implemented");
        // throw new javax.ws.rs.BadRequestException( "Invalid parameter value" );
        // throw new javax.ws.rs.NotFoundException( "MyExample not found" );
    }

Advantages:

  • the return type is a plain java object. Actually it is already an autogenerated class by swagger codegen.
    no needs to build an ApiResponseMessage
  • the error messages are suggested in comments together with elegant code to generate the error. the developer does not need to remember (or check) what is written in the OpenAPI spec.
  • it is still jaxrs compliant
Related issues/PRs

already mentioned here by @Tillerino. issue #4509

Suggest a fix/enhancement

I'm actually working on this improvement. I can provide a PR:
The source code modification affects the AbstractJavaJAXRSServerCodegen, so this enables more than one jaxrs implementation to adopt the described structure.
However I'm working only on the jaxrs/jersey template and finally comes my question:

It is better to create a new template or modify the existing one?
If it is better to create a new tempate a I've some question: how to create a new one? what name?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading AbstractJavaJAXRSServerCodegen and comparing the existing jaxrs/jersey template with the proposed WebApplicationException-based output. Determine whether the existing template can support plain DTO return types and suggested JAX-RS exceptions, or whether a separate template is needed. Done means the chosen JAX-RS generation path produces compliant methods with the described error-handling comments and exception structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.