swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
17.09k stars 6.03k forks source link

No way to get HTTP headers in JAXRS CXF response #7447

Open shuawest opened 6 years ago

shuawest commented 6 years ago
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;
    ...
}
shuawest commented 6 years ago

It looks like I could also switch to the generic response, but that doesn't appear to be working in 2.2.2. I can only generate an API with the List return type instead of the generic CXF one. [JaxRS*] javax.ws.rs.core.Response vs. returnTypes #4713

It would still be best to have a wrapper entity when you need data from header.