0

Similar Problem : Use object type query param in swagger documentation

My ask :

I have an API for which lets I have 3 query parameters but in the future, it can have multiple parameters with different datatypes. So instead of directly mentioning them in my api-doc.yaml I want to create a model(class) which can hold all these parameters. Please note I only want to go with this solution. I know we can pass it in the body. But I am in a tightly coupled setup hence I am interested to see how we can wrap these parameters into a single class

My current implementation: My api-defs.yaml file where I am defining this model as a schema PayloadQueryParams

PayloadQueryParams:
  type: object
  properties:
    workflow:
      type: string
      required: true
    timestamp:
      type: integer
      format: int64
      required : true
    createdTill:
      type: integer
      format: int64
      description: "timestamp in ms for querying scheduler service tasks"
      required : false
    page:
      type: integer
      description: "page number for scheduled tasks"
      required: false

Now I am trying to use this model, into my api-internal.yaml

  /tasks:
    get:
      tags:
        - "internal"
      operationId: "getTask"
      parameters:
        - in: query
          name : PayloadQueryParams
          schema:
            $ref: '#/components/schemas/PayloadQueryParams'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/ResponseModel'
        "401":
          description: "Unauthorized"
          content: { }
        "403":
          description: "Forbidden"
          content: { }

Now usually my approach stays is that with this codegen structure generates a custom boiler plater interface which I implement into my controller layer and override methods,

PROBLEM With above structure problem I am facing is

  1. The methods codegen is generating (getTask) that is created with model PayloadQueryParams which I expect it to do but the problem is when I am trying to send query parameters from the URLs its receiving it as null.
  2. As part of testing I removed all these definitions from swagger and created my own query paramter class PayloadQueryParams exactly same which was generated by swagger and when I try to use that directly into my controller layer, my UTs are working fine that means when I send the query params from URL they are parsed correctly
  3. But as I mentioned I cant go with the setup-2 I have to do same thing via swagger codegen
  4. I have validated by copying the exact definition of class PayloadQueryParams generated by swagger into my own custom class, even when they are identical, my APIs without swagger are working but not working when I used swagger codegen for generating query param model

SOLUTIONS I EXPECT

  1. Is there any structual problem in my yaml files ?
  2. I am on openAPI so I belive that is not the problem
  3. Is there any other way we can get these query parameters into a hashmap or multivalue map
Vaibhav Jain
  • 61
  • 1
  • 6
  • _"when I am trying to send query parameters from the URLs its receiving it as null."_ - this could be an issue with the specific server/client codegen that you used, or with the code you use to send the request. It's hard to say without seeing the code. – Helen Nov 08 '22 at 16:19
  • @Helen I doubt this could be the issue because I am using some UTs for the testing ,so to validate this first I ran the model generated by swagger and then I ran the model which I wrote manually the one which was created by me was successfull on TCs. I mean from my finding I believe there is either some problem in my yaml syntax or I am doubtful that can we pass the schema in the way I am using it for the query parameters – Vaibhav Jain Nov 08 '22 at 18:04
  • Your OpenAPI definition (and the usage of an object schema as a query parameter) is correct and means that the URL query string is formatted as `/tasks?workflow=...&timestamp=...&createdTill=...&page=...`. There's just one small error in the definition: the required object properties must be specified in the `required: [prop1, prop2, ...]` list on the object level ([example](https://stackoverflow.com/a/40113571/113116)); properties themselves don't have the `required: true/false` attribute. – Helen Nov 08 '22 at 18:48
  • Since the `PayloadQueryParams` schema lives in a separate file, you probably need to change the parameter schema `$ref` to: `$ref: 'path/to/api-defs.yaml#/PayloadQueryParams` or similar. – Helen Nov 08 '22 at 18:56
  • ok thanks @Helen, thanks for the input but on applying those above too I am not able to resolute it. Please do let me know if you have any reference examples where we are creating a custom model for query params or some reference for this, I spent a much time on this so I am going without any model for now – Vaibhav Jain Nov 10 '22 at 07:02

0 Answers0