A common use case for an API is one where you have a set of parameters for a call that may have a predefined value. Take pagination, for example, where the call allows you to ask for a specific page of query results. As a producer, you would probably allow the consumer to set the number of entries per page, but you’d also want to allow the consumer to get a predefined number of entries without sending it with each request.
Using the default value
This is where the default value comes in. In the Swagger specification, default allows you to set a value to parameters, models (and their properties) or response headers (the container). When those are omitted by either the client or the server, the receiving end should assume the default value.
The value of the default keyword is slightly unique in the Swagger specification. It is defined as Any but is meant to “copy” the type of its containing object. So if you have a parameter of type string, the value of default is expected to be string as well. Obviously, a non-matching type would not make sense as you’d be declaring that the property’s default value is of a different type than what is allowed. For body parameters of complex types, the default can represent a complex default value. Containers of array types should have an array structure for their default value as well.
You can find the default property in the spec at the following places:
Why use the default value?
Defining the value has a few benefits:
- As stated, it allows the omission of the parameter/property/header from the request, simplifying the process and minimizing required bandwidth.
- It helps to document the behavior of your API. If you specify a default value, your consumers know what to expect in the response.
- It allows for better API testing because the tester knows the expected result when the container is not specified.
Common mistakes when using the default value
There are two possible discrepancies when using the default value:
- Defining a default value for a container and marking that container as required is somewhat of a contradiction. If the container is required, it will always be sent and the default value will never take effect.
- The second case is using the default as a way to mention a sample value for its container. That is not the proper use of the field and can lead to unexpected behavior in some of the Swagger tools. Some containers offer alternative ways to setting a sample value.
Pro tip:
We have another use for the default keyword that’s quite different. It can be used under the responses section to mention a general purpose response for an API. Normally, you’d describe your successful responses, but sometimes you may have a generic way to expose errors, no matter which HTTP status code is used. In that case, you can use the default response and provide the common structure used by it.
For more information, check out the section in the specification - http://swagger.io/specification/#responsesDefault.