Issue #577: interface for paths

versions/3.0.md

@@ -269,6 +269,7 @@ Field Pattern | Type | Description
 <a name="parametersDefinitionsObject"></a> | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here.
 <a name="responseHeadersDefinitionsObject"></a> | [Response Headers Definitions Object](#responseHeadersDefinitionsObject) | Response headers to reuse across the specification.
 <a name="securityDefinitionsObject"></a> | [Security Definitions Object](#securityDefinitionsObject) | Security definitions to reuse across the specification.
+<a name="componentsInterfaces"></a> interfaces | [Interface Definitions Object](#interfacesDefinitionsObject) | Interface definitions to reuse in paths or URI properties in schemas.
 
 
 #### <a name="pathsObject"></a>Paths Object
@@ -333,7 +334,7 @@ A Path Item may be empty, due to [ACL constraints](#securityFiltering). The path
 
 Field Name | Type | Description
 ---|:---:|---
-<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*.
+<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.
 <a name="pathItemSummary"></a>summary | An optional, string summary, intended to apply to all operations in this path.
 <a name="pathItemDescription"></a>description | An optional, string description, intended to apply to all operations in this path.
 <a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
@@ -430,9 +431,178 @@ parameters:
   collectionFormat: csv
 ```
 
+##### Path Item Object example (using an interface)
+
+This example refers to the pet-list example in the [Interface object](#interfaceObject).
+
+```js
+{
+  "$ref": "#/components/interfaces/pet-list", 
+  "parameters": [
+    {
+      "name": "id",
+      "in": "path",
+      "description": "IDs of pets to use",
+      "required": true,
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "collectionFormat": "csv"
+    }
+  ]
+}
+```
+
+```yaml
+$ref: '#/components/interfaces/pet-list'
+parameters:
+- name: id
+  in: path
+  description: ID of pet to use
+  required: true
+  type: array
+  items:
+    type: string
+  collectionFormat: csv
+```
+
+#### <a name="interfacesDefinitionsObject"></a> Interfaces Definitions Object
+
+The Interfaces definitions object defines named interfaces which can then be implemented by [path items](#pathItemObject) declared in the [Paths object](#pathsObject) or by URI properties in schemas.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+<a name="interfacesName"></a>{name} | [Interface Object](#schemaObject) | A single interface, mapping a "name" to the interface it defines.
+
+##### Interfaces Object Example
+
+```js
+{
+  "pet-list": {
+    "get": {
+      "description": "Returns a list of pets",
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "A list of pets.",
+          "schema": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/pet"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+```yaml
+pet-list:
+  get:
+    description: Returns a list of pets
+    produces:
+    - application/json
+    responses:
+      '200':
+        description: A list of pets.
+        schema:
+          type: array
+          items:
+            $ref: '#/definitions/pet'
+```
+
+
+#### <a href="interfaceObject"></a> Interface object
+
+An interface defines a set of operations which can be implemented by a path item, or by a URI property in a schema.
+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.
+
+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.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+<a name="interfaceGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
+<a name="interfacePut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
+<a name="interfacePost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
+<a name="interfaceDelete"></a>delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
+<a name="interfaceOptions"></a>options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
+<a name="interfaceHead"></a>head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
+<a name="interfacePatch"></a>patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
+<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.
+
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+<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. 
+
+##### Interface Item Object Example
+
+
+
+```js
+{
+  "get": {
+    "description": "Returns list of pets",
+    "summary": "retrieve list of pets",
+    "produces": [
+      "application/json",
+      "text/html"
+    ],
+    "responses": {
+      "200": {
+        "description": "pet response",
+        "schema": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Pet"
+          }
+        }
+      },
+      "default": {
+        "description": "error payload",
+        "schema": {
+          "$ref": "#/definitions/ErrorModel"
+        }
+      }
+    }
+  }
+}
+```
+
+```yaml
+get:
+  description: returns a list of pets
+  summary: retrieve list of pets
+  produces:
+  - application/json
+  - text/html
+  responses:
+    '200':
+      description: pet response
+      schema:
+        type: array
+        items:
+          $ref: '#/definitions/Pet'
+    default:
+      description: error payload
+      schema:
+        $ref: '#/definitions/ErrorModel'
+```
+
 #### <a name="operationObject"></a>Operation Object
 
-Describes a single API operation on a path.
+Describes a single API operation on a path or an interface.
 
 ##### Fixed Fields
 
@@ -445,7 +615,7 @@ Field Name | Type | Description
 <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.
 <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).
 <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).
-<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.
+<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).
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <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. 
 <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 +1484,7 @@ Field Name | Type | Description
 ---|:---:|---
 <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.
 <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`.
+<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.) 
 <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.
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
 <a name="schemaExample"></a>example | Any | A free-form property to include a an example of an instance for this schema.