How to define a header parameter's default value is in OpenAPI 3.0

Question

I have an endpoint that accepts a PUT without a body. The PUT causes an event to trigger on the backend, and our API design team decided that PUT was the best RESTful verb for the method's purpose.

The problem is when our Swagger renders our .yaml file, the sample cURL command it displays fails to run from a command prompt. Apparently curl does not like to do a PUT without a body, unless it includes the header value: Content-Length: 0. The method returns 200-OK when called by the 'execute' button on the rendered page, but not from the generated curl command.

How do I add a default value in the OpenAPI Spec so the header would be included by the Swagger renderer when it generates the example curl command?

Here is an example of our method in the .yaml file:

'/{jobId}/start':
  parameters:
    - in: header
      name: Content-Length
      schema:
        type: string
  put:
    summary: Starts processing job
    tags:
      - Actions
    responses:
      '200':
        description: OK
    description: Starts processing job

I tried to use the default keyword but my editor (Visual Studio Code) indicates it's not a valid Property. And I cannot find anywhere in OpenAPI Specificiation on how to default a header parameter's value.

Answer 1

If you define a parameter to your put method with the fromheader decoration and correct value it will generate what you want. Example:

[HttpPut]
public Task<ActionResult> Put([FromHeader(Name = "Content-Length")] string foo = "0")
{
     // execute anything here               
     return NoContent();
}

edit:

My example generates openapi document the way you wanted it. I see a slight difference against your example. In my example parameters is part op de http operation (put). And default is part of schema. In yaml this will look as:

'/{jobId}/start':
  put:
    summary: Starts processing job
    tags:
      - Actions
    parameters:
      - name: Content-Length
        in: header
        schema:
          type: string
          default: "0"
          nullable: true
    responses:
      '200':
        description: OK
    description: Starts processing job

In your example it is part of the path which is incorrect according: https://swagger.io/docs/specification/paths-and-operations/