swagger-api / swagger-api/swagger-codegen

No way to get HTTP headers in JAXRS CXF response

Open
#7,447 1 comment 0 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

I'm creating a JAXRS CXF swagger spec for an existing REST/JSON API that I don't control. The API has a number of paginated result sets where the response is an array as a body payload, and puts before/after markers in the HTTP response header.

Swagger-codegen version

swagger-jaxrs 2.2.3
swagger-codegen-maven-plugin 2.2.3 with language jaxrs-cxf

Swagger declaration file content or url

https://docs.gdax.com/#pagination

Clip of the mocked up / expected Swagger spec with pagination in response header

  /products/{product-id}/trades:
    get:
      operationId: getTrades
      summary: Get Trades for Product [paginated]
      description: |
        List the latest trades for a product.  This request is paginated.
        The trade 'side' indicates the maker order side. The maker order is the order that was open on the order book. buy side indicates a down-tick because the maker was a buy order and their order was removed. Conversely, sell side indicates an up-tick.
      tags:
        - Public > Market Data
      parameters:
        - name: product-id
          in: path
          description: Id of the product to get the trades for
          required: true
          type: string
        - $ref: '#/parameters/pagBeforeParam'
        - $ref: '#/parameters/pagAfterParam'
        - $ref: '#/parameters/limitParam'
      responses:
        '200':
          description: Trades
          schema:
            type: array
            items:
              $ref: '#/definitions/Trade'
          headers:
            cb-before:
              type: integer
              format: int64
              description: Pagination cursor for requesting previous pages.
            cb-after:
              type: integer
              format: int64
              description: Pagination cursor for requesting following pages.
        '429':
          description: Rate limit exceeded. GDAX throttles public endpoints by IP 3 requests per second, up to 6 requests per second in bursts.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
Suggest a fix/enhancement

Allow for a response wrapper to be generated such the response body is an element of a response object. Allow the Swagger/OpenAPI spec author to use the responses>headers>{header-key} yaml to define which headers should be in the response object. Allow backward compatibility by controlling the response wrapping behavior with a codegen parameter.

Wrapper 'off' generates API method:
public List getTrades(String productId, long before, long after, long limit);

Wrapper 'on' generates (new bahavior):
public TradeResponse getTrades(String productId, long before, long after, long limit);

public class TradeResponse {
    private List<Trade> trades;
    private Long cbBefore;
    private Long cbAfter;
    ...
}

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 examining the jaxrs-cxf generator and its generated API method signatures, using the Swagger response headers example as the input case. Define how a response wrapper and its header fields should be represented while preserving the current unwrapped behavior through a codegen parameter. Done means the generated method can return the wrapper with body and declared headers, while legacy output remains available.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.