When we define a query, path or header parameter we cannot use a reference to an existing definition.
If I create a Username definition to describe a string which is a username with a certain length and a regex pattern, I can use it in any definition I want.
But if I want to describe a Username path parameter with the same characteristics, I cannot use a schema (only availble if in value is body). So I'll have to define again the characteristics of this Username atomic definition in the UsernameParameter.
Before: Username is described twice
paths:
/persons/{username}:
get:
parameters:
- $ref: '#/parameters/UsernameParameter'responses:
'200':
description: A personschema:
$ref: '#/definitions/Person'definitions:
Username:
description: A person's usernametype: stringpattern: '[a-z0-9]{8,64}'minLength: 8maxLength: 64Person:
properties:
username:
# we can reference the atomic definition Username in any definition$ref: '#/definitions/Username'firstname:
type: stringlastname:
type: stringfriends:
type: arrayitems:
# we can reference the atomic definition Username in any definition$ref: '#/definitions/Friend'Friend:
properties:
username:
$ref: '#/definitions/Username'parameters:
UsernameParameter:
name: usernamein: pathrequired: true# but we cannot reference the atomic definition Username in atomic parameters# username is described twicedescription: A person's usernametype: stringpattern: '[a-z0-9]{8,64}'minLength: 8maxLength: 64If we could use schema: Username is described only once
paths:
/persons/{username}:
get:
parameters:
- $ref: '#/parameters/UsernameParameter'responses:
'200':
description: A personschema:
$ref: '#/definitions/Person'definitions:
Username:
description: A person's usernametype: stringpattern: '[a-z0-9]{8,64}'minLength: 8maxLength: 64Person:
properties:
username:
$ref: '#/definitions/Username'firstname:
type: stringlastname:
type: stringfriends:
type: arrayitems:
$ref: '#/definitions/Friend'Friend:
properties:
username:
$ref: '#/definitions/Username'parameters:
UsernameParameter:
name: usernamein: pathrequired: true# username can be used in an atomic parameted and is described onceschema:
$ref: '#/definitions/Username'
When we define a query, path or header parameter we cannot use a reference to an existing definition.
If I create a Username definition to describe a string which is a username with a certain length and a regex pattern, I can use it in any definition I want.
But if I want to describe a Username path parameter with the same characteristics, I cannot use a schema (only availble if
invalue isbody). So I'll have to define again the characteristics of this Username atomic definition in the UsernameParameter.Before: Username is described twice
If we could use schema: Username is described only once