Skip to content

Commit 8e849d6

Browse files
ePaulPaŭlo Ebermann
ePaul
authored and
Paŭlo Ebermann
committed
Issue OAI#577: draft specification changes.
This simply reuses the $ref property of a path item – not sure if that is the right thing to do, or if we should use an `interface` property instead.
1 parent 082772c commit 8e849d6

File tree

1 file changed

+173
-3
lines changed

1 file changed

+173
-3
lines changed

‎versions/3.0.md

Lines changed: 173 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ A Path Item may be empty, due to [ACL constraints](#securityFiltering). The path
333333

334334
Field Name | Type | Description
335335
---|:---:|---
336-
<a name="pathItemRef"></a>$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*.
336+
<a name="pathItemRef"></a>$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. The referenced structure also can be an [interface object](#interfaceObject). In this case the path is implementing the interface. If the path contains any parameter placeholders, these need to be declared in the [parameters property](#pathItemParameters), as an interface can't declare path parameters itself.
337337
<a name="pathItemSummary"></a>summary | An optional, string summary, intended to apply to all operations in this path.
338338
<a name="pathItemDescription"></a>description | An optional, string description, intended to apply to all operations in this path.
339339
<a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
@@ -430,9 +430,178 @@ parameters:
430430
collectionFormat: csv
431431
```
432432

433+
##### Path Item Object example (using an interface)
434+
435+
This example refers to the pet-list example in the [Interface object](#interfaceObject).
436+
437+
```js
438+
{
439+
"$ref": "#/interfaces/pet-list",
440+
"parameters": [
441+
{
442+
"name": "id",
443+
"in": "path",
444+
"description": "IDs of pets to use",
445+
"required": true,
446+
"type": "array",
447+
"items": {
448+
"type": "string"
449+
},
450+
"collectionFormat": "csv"
451+
}
452+
]
453+
}
454+
```
455+
456+
```yaml
457+
$ref: '#/interfaces/pet-list'
458+
parameters:
459+
- name: id
460+
in: path
461+
description: ID of pet to use
462+
required: true
463+
type: array
464+
items:
465+
type: string
466+
collectionFormat: csv
467+
```
468+
469+
#### <a name="interfacesObject"></a> Interfaces Object
470+
471+
The Interfaces objects defines named interfaces which can then be implemented by [path items](#pathItemObject) declared in the [Paths object](#pathsObject) or by URI properties in schemas.
472+
473+
##### Patterned Fields
474+
475+
Field Pattern | Type | Description
476+
---|:---:|---
477+
<a name="interfacesName"></a>{name} | [Interface Object](#schemaObject) | A single interface, mapping a "name" to the interface it defines.
478+
479+
##### Interfaces Object Example
480+
481+
```js
482+
{
483+
"pet-list": {
484+
"get": {
485+
"description": "Returns a list of pets",
486+
"produces": [
487+
"application/json"
488+
],
489+
"responses": {
490+
"200": {
491+
"description": "A list of pets.",
492+
"schema": {
493+
"type": "array",
494+
"items": {
495+
"$ref": "#/definitions/pet"
496+
}
497+
}
498+
}
499+
}
500+
}
501+
}
502+
}
503+
```
504+
505+
```yaml
506+
pet-list:
507+
get:
508+
description: Returns a list of pets
509+
produces:
510+
- application/json
511+
responses:
512+
'200':
513+
description: A list of pets.
514+
schema:
515+
type: array
516+
items:
517+
$ref: '#/definitions/pet'
518+
```
519+
520+
521+
#### <a href="interfaceObject"></a> Interface object
522+
523+
An interface defines a set of operations which can be implemented by a path item, or by a URI property in a schema.
524+
An interface object might be empty, due to [ACL constraints](#securityFiltering). The existence of the interface itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
525+
526+
An interface doesn't define any path parameters, and also can't define any host, scheme or port properties. These come either from the path item or are included in the URI implementing this interface. The same applies for operation objects included in an interface.
527+
528+
##### Fixed Fields
529+
530+
Field Name | Type | Description
531+
---|:---:|---
532+
<a name="interfaceGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
533+
<a name="interfacePut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
534+
<a name="interfacePost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
535+
<a name="interfaceDelete"></a>delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
536+
<a name="interfaceOptions"></a>options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
537+
<a name="interfaceHead"></a>head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
538+
<a name="interfacePatch"></a>patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
539+
<a name="interfaceParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this interface. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). There can be one "body" parameter at most. There MUST be no parameters with location "path" in this list.
540+
541+
542+
##### Patterned Fields
543+
544+
Field Pattern | Type | Description
545+
---|:---:|---
546+
<a name="interfaceExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details.
547+
548+
##### Interface Item Object Example
549+
550+
551+
552+
```js
553+
{
554+
"get": {
555+
"description": "Returns list of pets",
556+
"summary": "retrieve list of pets",
557+
"produces": [
558+
"application/json",
559+
"text/html"
560+
],
561+
"responses": {
562+
"200": {
563+
"description": "pet response",
564+
"schema": {
565+
"type": "array",
566+
"items": {
567+
"$ref": "#/definitions/Pet"
568+
}
569+
}
570+
},
571+
"default": {
572+
"description": "error payload",
573+
"schema": {
574+
"$ref": "#/definitions/ErrorModel"
575+
}
576+
}
577+
}
578+
}
579+
}
580+
```
581+
582+
```yaml
583+
get:
584+
description: returns a list of pets
585+
summary: retrieve list of pets
586+
produces:
587+
- application/json
588+
- text/html
589+
responses:
590+
'200':
591+
description: pet response
592+
schema:
593+
type: array
594+
items:
595+
$ref: '#/definitions/Pet'
596+
default:
597+
description: error payload
598+
schema:
599+
$ref: '#/definitions/ErrorModel'
600+
```
601+
433602
#### <a name="operationObject"></a>Operation Object
434603

435-
Describes a single API operation on a path.
604+
Describes a single API operation on a path or an interface.
436605

437606
##### Fixed Fields
438607

@@ -445,7 +614,7 @@ Field Name | Type | Description
445614
<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
446615
<a name="operationConsumes"></a>consumes | [`string`] | A list of MIME types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
447616
<a name="operationProduces"></a>produces | [`string`] | A list of MIME types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
448-
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). There can be one "body" parameter at most.
617+
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters) or [Interface](#interfaceParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). There can be one "body" parameter at most. If this operation is contained in an interface definition, the parameters can't have a location of `path` (because there is no path which could contain the corresponding placeholder).
449618
<a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
450619
<a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition.
451620
<a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
@@ -1314,6 +1483,7 @@ Field Name | Type | Description
13141483
---|:---:|---
13151484
<a name="schemaDiscriminator"></a>discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it.
13161485
<a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as `readOnly` being `true` SHOULD NOT be in the `required` list of the defined schema. Default value is `false`.
1486+
<a name="schemaInterface"></a>interface | [Interface Object](#interfaceObject)|[Reference Object](#referenceObject) | For properties of type `string`, this (optional) property declares that the value is an URI, and the resource identified by this URI implements the given (or usually referred) interface. (This allows the receiver to actually use the URI without trying to parse it.)
13171487
<a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
13181488
<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
13191489
<a name="schemaExample"></a>example | Any | A free-form property to include a an example of an instance for this schema.

0 commit comments

Comments
 (0)