Renamed some components for consistency
MODIFY
versions/3.0.md
versions/3.0.md
@@ -27,7 +27,7 @@ Additional utilities can also take advantage of the resulting files, such as tes
- [Format](#format)
- [File Structure](#fileStructure)
- [Data Types](#dataTypes)
- - [Relative References In Urls](#relativeReferences)
+ - [Relative References In URLs](#relativeReferences)
- [Schema](#schema)
- [OpenAPI Object](#oasObject)
- [Info Object](#infoObject)
@@ -49,8 +49,8 @@ Additional utilities can also take advantage of the resulting files, such as tes
- [Examples Object](#examplesObject)
- [Links Object](#linksObject)
- [Link Object](#linkObject)
- - [Variable substitution](#variableSubstitution)
- - [Link Parameters](#linkParametersObject)
+ - [Variable Substitution](#variableSubstitution)
+ - [Link Parameters Object](#linkParametersObject)
- [Header Object](#headerObject)
- [Tag Object](#tagObject)
- [Examples Object](#examplesObject)
@@ -159,7 +159,7 @@ date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.
dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
password | `string` | `password` | Used to hint UIs the input needs to be obscured.
-### <a name="relativeReferences"></a>Relative References In URLs
+### <a name="relativeReferences"></a>Relative References in URLs
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Relative references are resolved using the URLs defined in the [Servers array](#servers) as a Base URI.
@@ -398,13 +398,13 @@ All objects defined within the components object will have no effect on the API
Field Pattern | Type | Description
---|:---|---
-<a name="componentsDefinitions"></a> definitions | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
<a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject).
<a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
<a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
<a name="componentsHeaders"></a> headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject).
-<a name="componentsSecurityDefinitions"></a> securityDefinitions| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
+<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
<a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject)] | An object to hold reusable [Link Objects](#linkObject).
<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject)] | An object to hold reusable [Callback Objects](#callbackObject).
@@ -421,11 +421,11 @@ my.org.User
my\org\User
```
-##### Definitions Object Example
+##### Components Object Example
```json
"components": {
- "definitions": {
+ "schemas": {
"Category": {
"type": "object",
"properties": {
@@ -486,13 +486,13 @@ my\org\User
"content": {
"application/json": {
"schema": {
- "$ref": "#/definitions/GeneralError"
+ "$ref": "#/components/schemas/GeneralError"
}
}
}
}
},
- "securityDefinitions": {
+ "securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "api_key",
@@ -516,7 +516,7 @@ my\org\User
```yaml
components:
- definitions:
+ schemas:
Category:
type: object
properties:
@@ -560,8 +560,8 @@ components:
content:
application/json
schema:
- $ref: '#/definitions/GeneralError'
- securityDefinitions:
+ $ref: '#/components/schemas/GeneralError'
+ securitySchemas:
api_key:
type: apiKey
name: api_key
@@ -606,7 +606,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
"schema": {
"type": "array",
"items": {
- "$ref": "#/definitions/pet"
+ "$ref": "#/components/schemas/pet"
}
}
}
@@ -630,7 +630,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
schema:
type: array
items:
- $ref: '#/definitions/pet'
+ $ref: '#/components/schemas/pet'
```
#### <a name="pathItemObject"></a>Path Item Object
@@ -676,7 +676,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
"schema": {
"type": "array",
"items": {
- "$ref": "#/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
}
}
}
@@ -687,7 +687,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
"content": {
"text/html": {
"schema": {
- "$ref": "#/definitions/ErrorModel"
+ "$ref": "#/components/schemas/ErrorModel"
}
}
}
@@ -723,13 +723,13 @@ get:
schema:
type: array
items:
- $ref: '#/definitions/Pet'
+ $ref: '#/components/schemas/Pet'
default:
description: error payload
content:
'text/html':
schema:
- $ref: '#/definitions/ErrorModel'
+ $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
in: path
@@ -1120,13 +1120,13 @@ A request body with a referenced model definition.
"content": {
"application/json": {
"schema": {
- "$ref": "#/definitions/User"
+ "$ref": "#/components/schemas/User"
},
"examples": [ "http://foo.bar/examples/user-example.json" ]
},
"application/xml": {
"schema": {
- "$ref": "#/definitions/User"
+ "$ref": "#/components/schemas/User"
},
"examples": [ "http://foo.bar/examples/user-example.xml" ]
},
@@ -1147,12 +1147,12 @@ description: user to add to the system
content:
'application/json':
schema:
- $ref: '#/definitions/User'
+ $ref: '#/components/schemas/User'
examples:
- 'http://foo.bar/examples/user-example.json'
'application/xml':
schema:
- $ref: '#/definitions/User'
+ $ref: '#/components/schemas/User'
examples:
- 'http://foo.bar/examples/user-example.xml'
'text/plain':
@@ -1275,7 +1275,7 @@ Field Pattern | Type | Description
{
"application/json": {
"schema": {
- "$ref": "#/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
},
"examples": [{
"name": "Fluffy",
@@ -1292,7 +1292,7 @@ Field Pattern | Type | Description
```yaml
application/json:
schema:
- $ref: "#/definitions/Pet"
+ $ref: "#/components/schemas/Pet"
examples:
# converted directly from YAML to JSON
- name: Fluffy
@@ -1411,7 +1411,7 @@ requestBody:
# default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
type: array
items:
- type: '#/definitions/Address'
+ type: '#/components/schemas/Address'
```
In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced. This attribute is _only_ applicable to `multipart/*` and `x-www-form-urlencoded` request bodies.
@@ -1514,7 +1514,7 @@ A 200 response for successful operation and a default response for others (imply
"content": {
"application/json": {
"schema": {
- "$ref": "#/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
}
}
}
@@ -1524,7 +1524,7 @@ A 200 response for successful operation and a default response for others (imply
"content": {
"application/json": {
"schema": {
- "$ref": "#/definitions/ErrorModel"
+ "$ref": "#/components/schemas/ErrorModel"
}
}
}
@@ -1538,13 +1538,13 @@ A 200 response for successful operation and a default response for others (imply
content:
application/json:
schema:
- $ref: '#/definitions/Pet'
+ $ref: '#/components/schemas/Pet'
default:
description: Unexpected error
content:
application/json:
schema:
- $ref: '#/definitions/ErrorModel'
+ $ref: '#/components/schemas/ErrorModel'
```
#### <a name="responseObject"></a>Response Object
@@ -1583,7 +1583,7 @@ Response of an array of a complex type:
"schema": {
"type": "array",
"items": {
- "$ref": "#/definitions/VeryComplexType"
+ "$ref": "#/components/schemas/VeryComplexType"
}
}
}
@@ -1598,7 +1598,7 @@ content:
schema:
type: array
items:
- $ref: '#/definitions/VeryComplexType'
+ $ref: '#/components/schemas/VeryComplexType'
```
Response with a string type:
@@ -1768,7 +1768,7 @@ myWebhook:
content:
'application/json'
schema:
- $ref: '#/components/definitions/SomePayload'
+ $ref: '#/components/schemas/SomePayload'
responses:
200:
description: webhook successfully processed an no retries will be performed
@@ -1867,7 +1867,7 @@ Field Name | Type | Description
Field Pattern | Type | Description
---|:---:|---
-<a name="linkName"></a>link name | [Link Object](#linkObject) | A short name for the link, following the naming constraints of the <a href="#definitionsName">definitions name</a>.
+<a name="linkName"></a>link name | [Link Object](#linkObject) | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
The link SHALL reference a single Link Object, or a JSON Reference to a single link object.
@@ -2061,7 +2061,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/definitions/user'
+ $ref: '#/components/schemas/user'
links:
userRepositories:
$ref: '#/components/links/UserRepositories'
@@ -2081,7 +2081,7 @@ paths:
schema:
type: array
items:
- $ref: '#/components/definitions/repository'
+ $ref: '#/components/schemas/repository'
links:
userRepository:
$ref: '#/components/links/UserRepository'
@@ -2103,7 +2103,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/definitions/repository'
+ $ref: '#/components/schemas/repository'
links:
repositoryPullRequests:
$ref: '#/components/links/RepositoryPullRequests'
@@ -2134,7 +2134,7 @@ paths:
schema:
type: array
items:
- $ref: '#/components/definitions/pullrequest'
+ $ref: '#/components/schemas/pullrequest'
/2.0/repositories/{username}/{slug}/pullrequests/{pid}:
get:
operationId: getPullRequestsById
@@ -2157,7 +2157,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/definitions/pullrequest'
+ $ref: '#/components/schemas/pullrequest'
links:
$ref: '#/components/links/PullRequestMerge'
/2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge:
@@ -2182,18 +2182,18 @@ paths:
components:
links:
UserRepositories:
- # returns array of '#/components/definitions/repository'
+ # returns array of '#/components/schemas/repository'
operationId: getRepositoriesByOwner
parameters:
username: $response.body#/username
UserRepository:
- # returns '#/components/definitions/repository'
+ # returns '#/components/schemas/repository'
operationId: getRepository
parameters:
username: $response.body#/owner/username
slug: $response.body#/slug
RepositoryPullRequests:
- # returns '#/components/definitions/pullrequest'
+ # returns '#/components/schemas/pullrequest'
operationId: getPullRequestsByRepository
params:
username: $response.body#/owner/username
@@ -2205,7 +2205,7 @@ components:
username: $response.body#/user/username # Should be $response.author.username?
slug: $response.body#/repository/slug
pid: $response.body#/id
- definitions:
+ schemas:
user:
type: object
properties:
@@ -2219,7 +2219,7 @@ components:
slug:
type: string
owner:
- $ref: '#/components/definitions/user'
+ $ref: '#/components/schemas/user'
pullrequest:
type: object
properties:
@@ -2228,9 +2228,9 @@ components:
title:
type: string
repository:
- $ref: '#/components/definitions/repository'
+ $ref: '#/components/schemas/repository'
author:
- $ref: '#/components/definitions/user'
+ $ref: '#/components/schemas/user'
```
As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `href`:
@@ -2239,7 +2239,7 @@ As references to `operationId` MAY NOT be possible (the `operationId` is an opti
components:
links:
UserRepositories:
- # returns array of '#/components/definitions/repository'
+ # returns array of '#/components/schemas/repository'
href: '/2.0/repositories/{$response.body#/username}'
```
@@ -2249,7 +2249,7 @@ or an absolute `href`:
components:
links:
UserRepositories:
- # returns array of '#/components/definitions/repository'
+ # returns array of '#/components/schemas/repository'
href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body#/username}'
```
@@ -2357,7 +2357,7 @@ are not compatible.
```yaml
# in a model
-definitions:
+schemas:
properties:
name:
type: string
@@ -2369,7 +2369,7 @@ definitions:
content:
'application/json':
schema:
- $ref: '#/definitions/Address'
+ $ref: '#/components/schemas/Address'
examples:
- {"foo": "bar"}
- {"bar": "baz"}
@@ -2397,7 +2397,7 @@ definitions:
content:
application/json:
schema:
- $ref: '#/definitions/SuccessResponse'
+ $ref: '#/components/schemas/SuccessResponse'
example:
$ref: http://foo.bar#/examples/address-example.json
```
@@ -2421,12 +2421,12 @@ This object cannot be extended with additional properties and any properties add
```json
{
- "$ref": "#/components/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
}
```
```yaml
-$ref: '#/components/definitions/Pet'
+$ref: '#/components/schemas/Pet'
```
##### Relative Schema File Example
@@ -2561,7 +2561,7 @@ format: email
"type": "string"
},
"address": {
- "$ref": "#/components/definitions/Address"
+ "$ref": "#/components/schemas/Address"
},
"age": {
"type": "integer",
@@ -2580,7 +2580,7 @@ properties:
name:
type: string
address:
- $ref: '#/components/definitions/Address'
+ $ref: '#/components/schemas/Address'
age:
type: integer
format: int32
@@ -2612,7 +2612,7 @@ For a string to model mapping:
{
"type": "object",
"additionalProperties": {
- "$ref": "#/components/definitions/ComplexModel"
+ "$ref": "#/components/schemas/ComplexModel"
}
}
```
@@ -2620,7 +2620,7 @@ For a string to model mapping:
```yaml
type: object
additionalProperties:
- $ref: '#/components/definitions/ComplexModel'
+ $ref: '#/components/schemas/ComplexModel'
```
###### Model with Example
@@ -2711,7 +2711,7 @@ examples:
```json
{
- "definitions": {
+ "schemas": {
"ErrorModel": {
"type": "object",
"required": [
@@ -2732,7 +2732,7 @@ examples:
"ExtendedErrorModel": {
"allOf": [
{
- "$ref": "#/definitions/ErrorModel"
+ "$ref": "#/components/schemas/ErrorModel"
},
{
"type": "object",
@@ -2752,7 +2752,7 @@ examples:
```
```yaml
-definitions:
+schemas:
ErrorModel:
type: object
required:
@@ -2767,7 +2767,7 @@ definitions:
maximum: 600
ExtendedErrorModel:
allOf:
- - $ref: '#/definitions/ErrorModel'
+ - $ref: '#/components/schemas/ErrorModel'
- type: object
required:
- rootCause
@@ -2780,7 +2780,7 @@ definitions:
```json
{
- "definitions": {
+ "schemas": {
"Pet": {
"type": "object",
"discriminator": "petType",
@@ -2801,7 +2801,7 @@ definitions:
"description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
"allOf": [
{
- "$ref": "#/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
},
{
"type": "object",
@@ -2828,7 +2828,7 @@ definitions:
"description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
"allOf": [
{
- "$ref": "#/definitions/Pet"
+ "$ref": "#/components/schemas/Pet"
},
{
"type": "object",
@@ -2852,7 +2852,7 @@ definitions:
```
```yaml
-definitions:
+schemas:
Pet:
type: object
discriminator: petType
@@ -2867,7 +2867,7 @@ definitions:
Cat: ## "Cat" will be used as the discriminator value
description: A representation of a cat
allOf:
- - $ref: '#/definitions/Pet'
+ - $ref: '#/components/schemas/Pet'
- type: object
properties:
huntingSkill:
@@ -2884,7 +2884,7 @@ definitions:
Dog: ## "Dog" will be used as the discriminator value
description: A representation of a dog
allOf:
- - $ref: '#/definitions/Pet'
+ - $ref: '#/components/schemas/Pet'
- type: object
properties:
packSize:
@@ -3442,7 +3442,7 @@ read:pets: read your pets
#### <a name="securityRequirementObject"></a>Security Requirement Object
Lists the required security schemes to execute this operation.
-The name used for each property MUST correspond to a security scheme declared in the [Security Definitions](#componentsSecurityDefinitions) under the [Components Object](#componentsObject).
+The name used for each property MUST correspond to a security scheme declared in the [Security Definitions](#componentsSecuritySchemes) under the [Components Object](#componentsObject).
Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
This enables support for scenarios where there multiple query parameters or HTTP headers are required to convey security information.

Renamed some components for consistency