133 lines
3.5 KiB
Markdown
133 lines
3.5 KiB
Markdown
# 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
|
|
|
|
>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" (Reference)
|
|
},
|
|
{
|
|
"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" (Reference)
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"user"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
---
|
|
**Related Articles**
|
|
- [Referencing Another API Spec](/modeling/modeling-with-openapi/referencing-another-api-spec)
|
|
- [JSON Introduction](/modeling/json-best-practices/introduction)
|
|
|