Referencing Response Headers in Generated Response Schema

[sigmavirus24]

I'm working on an API where we're using JWS and we're intending to return a Replay-Nonce header in each response that we want to be able to be referenced in the generated code. Right now, we're only generating a Go client and the generated code is not providing anyway to access the header.

The OpenAPI YAML we are using looks like:

openapi: 3.0.0
info:
  title: Example
  version: 1.0.0

servers:
- url: https://example.net

paths:
  /new-nonce:
    head:
      operationId: RetrieveNewNonce
      responses:
        '200':
          headers:
            Replay-Nonce:
              $ref: '#/components/headers/ReplayNonce'
  /order:
    post:
      operationId: OrderItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nonce:
                  type: string
                title:
                  type: string
      responses:
        '201':
          headers:
            Replay-Nonce:
              $ref: '#/components/headers/ReplayNonce'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'

components:
  headers:
    ReplayNonce:
      schema:
        type: string
  schemas:
    OrderResponse:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string

We've also tried having separate request schema that we add additional code to generate a JWS that would look like:

requestBody:
  required: true
  content:
    application/json:  # application/jose+json doesn't work despite being a registered IANA media type
      properties:
        protected:
          type: string
        payload:
          type: string
        signature:
          type: string
      required: ['protected', 'payload', 'signature']

But that naturally doesn't change anything. The generated code from this has a client struct with

func (client *Client) RetrieveNewNonce(
	ctx context.Context,
) error {
// ...
}

(In other words, it's not returning anything other than an error)

Are we missing something? Is there syntax we're missing that would allow us to extract the value to the response struct?

[flaksp]

Is there syntax we're missing that would allow us to extract the value to the response struct?

Yep. response property should be responses. And you forgot to wrap media type object into content property. Here is fixed spec:

openapi: 3.0.0
info:
  title: Example
  version: 1.0.0

servers:
- url: https://example.net

paths:
  /new-nonce:
    head:
      operationId: RetrieveNewNonce
      responses:
        '200':
          headers:
            Replay-Nonce:
              $ref: '#/components/headers/ReplayNonce'
  /order:
    post:
      operationId: OrderItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nonce:
                  type: string
                title:
                  type: string
      responses:
        '201':
          headers:
            Replay-Nonce:
              $ref: '#/components/headers/ReplayNonce'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'

components:
  headers:
    ReplayNonce:
      schema:
        type: string
  schemas:
    OrderResponse:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string

application/jose+json doesn't work despite being a registered IANA media type

The OpenAPI specification does not require implementations to support all possible content types. Most implementations desire to support application/json only.

[sigmavirus24]

Thanks for responding @flaksp .I guess I wasn't very clear and I didn't do a good job typing an example out on my phone.

My concern is retrieving the value from the Replay-Nonce header to use in a subsequent request. That's what I'm struggling with. The rest of our internal API specification is valid and generates things correctly (except for the responses which should have some way of conveying the nonce value)

[handrews]

@sigmavirus24 this repository is for the specification only. You should raise your tooling support questions with the tooling vendor. Since the spec part of the question seems to have been answered, I'm going to close this as vendor-specific. Please comment if you think it should not be closed on those grounds.

[sigmavirus24]

I disagree @handrews (also hi again!). The specification regards headers as largely insignificant and has no recommendation for any implementation to do something with them requiring either custom generators or significant extension of multiple generators to do the right thing. Many generators don't provide this kind of functionality because the specification does not provide a way to indicate headers of significance that a user likely wants. Additionally, there's no way to indicate a header that can/must be used between requests.

Take the above example, there's no way to say "Clients should store and use this nonce from request to request and if they do not have it, retrieve one from the endpoint". This API is largely RESTful and should be specifiable by OpenAPI but it isn't.