Search code examples
apiblueprint

How to document optional parameters in path in API Blueprint?

Assume there is an API that has an optional parameter in in the URL path: 

## Get FooBar [/foo/bar/{type}]

+ Parameters
    + type (optional, string, `widget`) ... Filter for a specific bar type

Of course the type parameter should really be a query parameter, but the API implementation is as it is and can not be optimized.

Can this optionality of type be expressed in the URI Template?

Solution

  • Yes, you can show optional parameters, just prepend their block with a question mark.

    ## Get FooBar [/foo/bar/{?type}

+Parameters

     +type (optional) The widget type you want back, if any.