OpenAPI validation error for arrays passed through query string - Stack Overflow

admin管理员组

文章数量:1314480

We're trying to use an OpenAPI doc to validate the calls received by our backend when it goes through our firewall and we're having some issues when we need to pass an array through the querystring.

Here's a snippet of the OpenAPI doc we're using to validate this specific call:

openapi:  3.0.1
...
/api/pedidosassistencias/pesquisa:
    get:
      tags:
        - PedidosAssistencias
      summary:  Devolve uma lista paginada de pedidos de assistência compatível com os critérios indicados.
      description:  Devolve uma lista paginada ResumoPedidoAssistencia pedidos de assistência compatível com os critérios indicados.
      parameters:
        - name:  estados
          in:  query
          description:  Estados do pedido a filtrar
          schema:
            type:  array
            items:
              $ref:  '#/components/schemas/EstadoPedido'
            description:  Estados do pedido a filtrar
...

EstadoPedido is an enum (which means that the estados parameter's value can only have one of the values of that enum).

Whenever we pass the estados parameter through query string, we end up with an error. We've tried several approaches, but all of them end up generating an error:

// single parameter

https://XXX/api/pedidosassistencias/pesquisa?estados=2&idLocalTrabalho=100


// single parameter option 1
https://XXX/api/pedidosassistencias/pesquisa?estados[]=2&idLocalTrabalho=100

//single parameter option 2
https://XXX/api/pedidosassistencias/pesquisa?estados[0]=2&idLocalTrabalho=100

// several parameters option 1
https://XXX/api/pedidosassistencias/pesquisa?estados=2&estados=3&idLocalTrabalho=100


// several parameters option 2
https://XXX/api/pedidosassistencias/pesquisa?estados[]=2&estados[]=3&idLocalTrabalho=100

// several parameters option 3
https://XXX/api/pedidosassistencias/pesquisa?estados[0]=2&estados[1]=3&idLocalTrabalho=100

All of them failed with an Openapi validation query parameter violation error. When we remove the estados parameter from the query string, everything works out as expected.

Btw, initially, our calls were using the form estados[pos] in order to escape the duplicate parameter name check which is also performed by our firewall (the backend was build with net core 8, so it correctly translates the qs parameters into an array when using the [] syntax).

After reading the docs, I was convinced that this URL https://XXX/api/pedidosassistencias/pesquisa?estados=2&estados=3&idLocalTrabalho=100 should work without any issues (I assumed this because the docs say that the default serialization for querystring parameters is style: form and explode: true). However, the truth is that ouw firewall keeps saying that that the parameters don't match our openapi doc.

EDIT: while testing the remaining API, I've noticed that validation isn't working correctly either when there are "similar" routes. For instance, while trying to run a similar search for different resource using the URI /api/equipamentos/pesquisa, I've noticed that in this case the error says something like this:

API Validation violation - Path parameter "idEquipamento" validation failure : Failed to validate schema 

Which is weird because this method (endpoint) doesn't have a parameter called idEquipamento. After looking at the OpenAPI doc, I've noticed that besides the /api/equipamentos/pesquisa there's also a `/api/equipamentos/{idEquipamento}' path that looks like this:

/api/equipamentos/{idEquipamento}:
    get:
      parameters:
        - name: idEquipamento
          in: path
          required: true
          schema:
            type: integer
            description: Id do equipamento pai.
            format: int32

In this case, it seems like the validator matched the URI /api/equipamentos/pesquisa?... to /api/equipamentos/{idEquipamento} instead of /api/equipamentos/pesquisa which appears after in the document. So, maybe having similar paths is the reason why this validation is failing?

What might I be doing wrong? Maybe this is firewall bug while doing openapi validation?

本文标签： OpenAPI validation error for arrays passed through query stringStack Overflow