Path, query, header and cookie parameters

Path, query, header and cookie parameters are declared in the same way.

Let's see, for example, how to declare header and query parameters of a route

  • The header parameters are declared in a header block between braces.
  • The same way, query parameters are declared in a query block between braces

In these blocks each parameter is declared as the field of a type.

Simple example :

service Example{
    expose examples{ 
        route example{
            url:"example/id:String"
            header {
                headerParam1:String
                headerParam2:[Integer]
            }
            query{
                queryParam1:String
            }
            response:String 
        }
    }
}

Generated openAPI

As for the type fields, properties can be added between braces after the declaration of a parameter.

example

service Example2{
    expose examples{ 
        route example{
            url:"example/id:String"
            query{
                queryParam1:Integer{
                    description:"Description of the queryParam1 query parameter"
                    required:true
                    enum:[5,8,9,15]
                }
            }
            response:String 
        }
    }
}

Generated openAPI

Standard parameters properties :

 

  • description (String)
    • description of the field
  • comment (String)
    • Allows you to add a comment to the field
  • deprecated (Boolean)
    • indicates that this field is depracated and should not be used in the future.
  • regex (String)
    • Regular expression validating the possible values of the field.
  • enum (depends on the type of field)
    • list of allowed values
  • min (depends on the type of field)
    • minimum field value
  • max (depends on the type of field)
    • maximum field value
  • exclusiveMinimum (Boolean)
    •  Exclusion of the minimum value (defined by the min property)
  • exclusiveMaximum (Boolean)
    • Exclusion of the maximum value (defined by the max property)
  • minLength (Integer) - exclusively for String types
    • minimum string length
  • maxLength (Integer) - exclusively for String types
    • maximum String length
  • minItems (Integer) - exclusively for list
    • minimum number of items requested in the list
  • maxItems (Integer) - exclusively for list
    • maximum number of items accepted in the list
  • default (depends on the type of field)
    • default value if the field is missing.
  • nullable (Boolean)

    • accept null as value for this field

 

Response headers

Response headers are declared exactly the same same way as route parameters

The only difference is that they are declared at the response level and not at the route level

In order to declare headers for a response you must use the expanded response declaration form (responses)

Simple example

service Example3{
    expose examples{ 
        route example{
            url:"example/id:String"
            responses{
                "200":String{
                    headers {
                        x-headers1:String{
                            description:"My header 1"
                        }
                        x-headers2:Integer{
                            description:"My header 2"
                            enum:[4,6,12]
                        }
                    }
                }
            } 
        }
    }
}

Generated OpenAPI