swagger-api / swagger-api/swagger-core

@ApiResponse cannot infer parametrised type with Java Generics

Open
#4,355 5 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

I have the following code snippet

public class ApiStandardResponse<T> {
    T data;
}

and use that to annotate my endpoint

@Operation(
   ...
      responses = {
          @ApiResponse(
              responseCode = "200",
              description = "Success",
              content = {@Content(
                  mediaType = "application/json",
                  schema = @Schema(implementation = ApiStandardResponse.class)
              )}
          )
      }
   ...
  )

It turns out that there is no way to specify the parametrised type and thus swagger ui cannot infer it making it impossible for contract clients to generate the appropriate stubs

image

Is there an elegant way to specify the parametrised type somehow without using workarounds such as subclasses?

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 with the endpoint annotation using @ApiResponse, @Content, and @Schema(implementation = ApiStandardResponse.class), and reproduce the generated schema for ApiStandardResponse. Investigate how Java generic type information is represented in the OpenAPI output; done means the parametrized type is expressible without a subclass and Swagger UI and generated contract clients expose the correct response shape.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.