swagger-api / swagger-api/swagger-codegen
No way to get HTTP headers in JAXRS CXF response
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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