swagger-core

swagger-core copied to clipboard

Hello,

We're using Swagger annotations and Maven plugin to generate our spec. I'm attempting to add some @ApiResponse annotations to our operations, but the @Header annotation is not including the schema.type. For instance:

  @Operation(summary = "List of services for the given account",
             responses = {
                 @ApiResponse(responseCode = "200", description = "List of services for the given account"),
                 @ApiResponse(description = "User did not provide a valid auth token", responseCode = "401",
                              content = @Content(mediaType = MediaType.APPLICATION_JSON,
                                                 schema = @Schema(implementation = ErrorMessage.class)),
                              headers = { @Header(name = "testing-headers",
                                                  description = "Flow/trace ID for traceability in the logs",
                                                  schema = @Schema(type = "string")) })
             })

This generates the following spec:

    get:
      operationId: getServices
      parameters:
      - in: path
        name: accountId
        required: true
        schema:
          type:
          - string
      responses:
        "200":
          description: List of services for the given account
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          description: User did not provide a valid auth token
          headers:
            testing-headers:
              description: Flow/trace ID for traceability in the logs
              schema: {} # <- no `type: string` nested here 
              style: simple # <- not sure where this is coming from
      summary: List of services for the given account

Even if I add something like format to the @Schema:

    headers = { @Header(name = "testing-headers",
                        description = "Flow/trace ID for traceability in the logs",
                        schema = @Schema(type = "string", format = "hexadecimal")) })

            testing-headers:
              description: Flow/trace ID for traceability in the logs
              schema:
                format: hexadecimal
                # still no type
              style: simple

(Note that the motivation for adding the schema/type to the header is that linting tools complain about content/schema being required)