Update duplication-refs.md

2018-02-08 12:25:55 -06:00
parent ea1fac8cd9
commit 2b41569b14
1 changed files with 127 additions and 0 deletions
--- a/articles/modeling/duplication-refs.md
+++ b/articles/modeling/duplication-refs.md
@@ -1 +1,128 @@
+# Preventing Duplications and Simplifying OAS Files 
+
+## What 
+- API resources often have or share similar features 
+- Duplicating features increase the size and complexity of your API
+- Reusable definitions make it easier to read, understand, and update your OAS files
+- Similar features can be created as reusable definitions and utilized with references
+- These definitions can be hosted on the same server as your OAS file or on a different server 
+- You can reference a definition hosted at any location or server 
+- Apart from defining reusable definitions, you can also define reusable responses and parameters. You can store your reusable definitions, responses, and parameters in a common library. 
+
+<-- theme: info --> 
+>Key Terms: A definition is a named schema object. A reference is a path to a declaration within an OAS file.
+
+## How to Reference a Definition 
+To invoke a reference to a definition, use the **$ref** keyword. For example:
+```
+#/definitions/Pets ($ref: 'reference to definition')
+```
+
+## URL, Remote, and Local References 
+
+### General Syntax for URL Reference
+- Reference a complete document or resource located on a different server: 
+```
+$ref: 'http://url_resource_path'
+```
+- Reference a particular section of a resource stored on a different server: 
+```
+$ref: 'http://url_resource_path/document_name.json#section'
+```
+
+### General Syntax for Remote Reference
+- Reference a complete document or resource located on the same server and location: 
+```
+$ref:'document_name.json'
+```
+- Reference a particular section of a resource stored on a different server: 
+```
+$ref: 'document_name.json#section'
+```
+### General Syntax for Local Reference
+- Reference a resource found in the root of the current document and the definitions:
+```
+$ref: '#/definitions/section'
+```
+
+## Best Practices 
+- Only use $ref in locations specifed by the OpenAPI Specification 
+- Always enclose the value of your local reference in quotes (when using YAML syntax) to ensure it is not treated as a comment. For example:
+Good
+```
+"#/definitions/todo-partial"
+```
+Bad 
+```
+#/definitions/todo-partial
+```
+
+## Examples 
+- Assuming you have the following schema object named **Todo Partial** and you want to use it inside another definition: 
+
+```
+{
+  "title": "**Todo Partial**",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string" 
+    },
+    "completed": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "name",
+    "completed"
+  ]
+}
+```
+- To refer to that object, you need to add $ref with the corresponding path to your response: 
+
+```
+{
+  "title": "Todo Full",
+  "allOf": [
+    {
+      **"$ref": "#/definitions/todo-partial"**
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1000000
+        },
+        "completed_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "user": {
+          **"$ref: "https://exporter.stoplight.io/4568/master/common.oas2.yml#/definitions/user"**
+        }
+      },
+      "required": [
+        "id",
+        "user"
+      ]
+    }
+  ]
+}
+