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 ...
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.

      • yym's avatar
        yym
        New Contributor
        2 years ago

        Hi chichepo

         

        Thank you for you suggestions and examples. They were very helpful. I still on my way to find a solution.

        First of all, parameters can be the list of Reference Objects.

        The second, the Reference Object cannot be extended with additional properties and any properties added SHALL be ignored. Therefore the example in my upper post is incorrect. The field "in" should be removed.

        The third, according to $ref Syntax - $ref can be Local Reference, Remote Reference or URL Reference.

        Based on this information, I believe it is possible to reference files rather than components section in OAS.

         

         

        parameters:
        - $ref: 'https://<server>:<port>/parameters/queryParameters.json'
        - $ref: 'https://<server>:<port>/parameters/headerParameters.json'
        - $ref: 'https://<server>:<port>/parameters/pathParameters.json'