Forum Discussion

yym's avatar
yym
New Contributor
2 years ago

Using $ref in query parameters definition in OAS

Hi All.

I see that we can use $ref for Common Parameters for Various Paths but is it possible to use the same approach for query parameters?

Background: our data models are quite large and rich in parameters that can also be used in a GET requests as query parameters. That is why the query parameters definition in each OAS looks redundant. The idea is to use $ref, but this is explicitly not defined according to the OAS guide. Can I use such definition for query parameters?

 

/teams:
    get:
      summary: Gets a list of teams.
      parameters:
		- in: query
        - $ref: '#/parameters/queryParameters.json'
      responses:
        '200':
          description: OK

 

Thank you!

  • chichepo's avatar
    chichepo
    Champion Level 1
    2 years ago

    Hello yym 

    I am not sure if it fit to your need but I can suggest a quite different construction.
    We are also working with a huge volume of parameters in our API.

    First, you should consider to define your query parameters individually, within a dedicated domain:

     

    Of course, the schema description is defined within "schemas", in the domain:


    When done you can easily use the references in your API file:

     

     

    • yym's avatar
      yym
      New Contributor
      2 years ago

      Hi chichepo,

       

      Thank you for the answer!

      I'm a little bit confused because, as I see in the first snapshot, you define query parameters in the spec for the specific call POST EntityOperations. Actually, this is what I want to avoid.

      And in the third figure, you have a situation where parameters refer to components, and there they refer to the external files. I think it's too complicated, don't you? Why can't we reference directly to external files in the parameters avoiding components?

       parameters:
		- in: query
        - $ref: 'https://<server>:<port>/parameters/queryParameters.json'

       

      • chichepo's avatar
        chichepo
        Champion Level 1
        2 years ago

        yym 

        I am trying to make the parameters organization and calls as optimal as possible.

         

        You writed:
        "our data models are quite large and rich in parameters that can also be used in a GET requests as query parameters. That is why the query parameters definition in each OAS looks redundant."


        I am not sure if it is possible to use such kind of "generic" parameters file, as a reference, as shown in your example.

        The construction I suggest is including an API and a dedicated Domain, where I store my "reusable" parameters definitions (API file here and Domain file here).
        This is actually the best optimization I can imagine even for huge numbers of parameters.

        Don't hesitate to share with us any solutions you could find.