Defining Headers in Specific APIs

[abdullahabro]

How can we define required headers by a specific API route?

What I mean exactly is, let's say I have xx-orderSig-header, required by /createOrder, that is basically it will be hash generated by taking sha-256 of request body payload. And there can be many such other headers like xx-order-timestamp.

I am able to define req body type and APi response type and register them as schemas in Utoipa. I also see support for adding security headers by using a security tag (JWT, API keys).

But for defining normal headers, I can not find any example in the repo or docs.

I think i can use params tag some how to define headers, but currently there no option to tell utoipa that a param defined is actually a header not a request path or query param.

i want this to be generated

parameters:
      - name: xx-client-id
        in: header   << ---------------------------- See here
        description: client id used to indentify source of the requests
        required: true
        schema:
          type: string
        example: ts-cllient
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WithdrawRequest'
      required: true

Instead of this

     
     parameters:
        - name: xx-client-id
          in:path   << ---------------------------- See here
          description: client id used to indentify source of the requests
          required: true
          schema:
            type: string
          example: ts-cllient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequest'
        required: true

This is not an issue actually but more of a question and maybe a improvement in docs or examples, as headers are core component in REST APIs.

[juhaku]

@abdullahabro Yes you can, only way to do this for now is via tuple style params in #[utoipa::path(...)] macro as defined here: https://docs.rs/utoipa/latest/utoipa/attr.path.html#tuples.

E.g. define Header parameter as follows.

params(
    ("x-custom-header" = String, Header, description = "This is a custom header value"),
    ...
)

in Must be placed after name or parameter_type. Define the place of the parameter. This must be one of the variants of openapi::path::ParameterIn. E.g. Path, Query, Header, Cookie

Above is from the docs. This might be quite easy to skip over if one is not reading throughoughtly the docs and is quickly seeking the example for it. The docs could be improved a bit whereas the format of the tuple style params was made explicitly clear.