References¶
Using $ref statements, OpenAPI allows you to reference other parts of the schemas section. This means that a single definition for a property of an object can be used for multiple objects. This pattern is supported by OpenAlchemy. For example, the following OpenAPI specification makes use of references:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | openapi: "3.0.0"
info:
title: Test Schema
description: API to illustrate the OpenAlchemy $ref feature for a column.
version: "0.1"
paths:
/employee:
get:
summary: Used to retrieve all employees.
responses:
200:
description: Return all employees from the database.
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Employee"
components:
schemas:
Id:
type: integer
description: Unique identifier for the employee.
example: 0
x-primary-key: true
Name:
type: string
description: The name of the employee.
example: David Andersson
Division:
type: string
description: The part of the company the employee works in.
example: Engineering
Employee:
description: Person that works for a company.
type: object
x-tablename: employee
properties:
id:
$ref: "#/components/schemas/Id"
name:
$ref: "#/components/schemas/Name"
division:
$ref: "#/components/schemas/Division"
|
Which leads to the following models.py file:
1 2 3 | from open_alchemy import init_yaml
init_yaml("column-example-spec.yml", models_filename="column_models_auto.py")
|
The same is also possible for whole models which allows for aliases for models:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | openapi: "3.0.0"
info:
title: Test Schema
description: API to illustrate the OpenAlchemy $ref feature for a model.
version: "0.1"
paths:
/employee:
get:
summary: Used to retrieve all employees.
responses:
200:
description: Return all employees from the database.
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Employee"
components:
schemas:
Employee:
"$ref": "#/components/schemas/RefEmployee"
RefEmployee:
description: Person that works for a company.
type: object
x-tablename: employee
properties:
id:
type: integer
description: Unique identifier for the employee.
example: 0
x-primary-key: true
name:
type: string
description: The name of the employee.
example: David Andersson
division:
type: string
description: The part of the company the employee works in.
example: Engineering
|
Which leads to the following models.py file:
1 2 3 | from open_alchemy import init_yaml
init_yaml("model-example-spec.yml", models_filename="model_models_auto.py")
|
See also
Defining Relationships shows how to define object references that result in relationships between tables.
Inheritance shows how to use inheritance for schemas.
Remote References¶
The OpenAPI specification supports remote references in
another file within the file system and
a file available at a URL.
Warning
is not supported on Windows.
For (1), the following example shows how to reference a schema in another file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | openapi: "3.0.0"
info:
title: Test Schema
description: API to illustrate OpenAlchemy MVP.
version: "0.1"
paths:
/employee:
get:
summary: Used to retrieve all employees.
responses:
200:
description: Return all employees from the database.
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Employee"
components:
schemas:
Employee:
"$ref": "remote-example-spec.yml#/Employee"
|
The schema in the remote file is unchanged:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | Employee:
description: Person that works for a company.
type: object
x-tablename: employee
properties:
id:
type: integer
description: Unique identifier for the employee.
example: 0
x-primary-key: true
x-autoincrement: true
name:
type: string
description: The name of the employee.
example: David Andersson
x-index: true
division:
type: string
description: The part of the company the employee works in.
example: Engineering
x-index: true
salary:
type: number
description: The amount of money the employee is paid.
example: 1000000.00
required:
- name
- division
|
For (2), the following example shows how to reference a schema at a URL:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | openapi: "3.0.0"
info:
title: Test Schema
description: API to illustrate OpenAlchemy MVP.
version: "0.1"
paths:
/employee:
get:
summary: Used to retrieve all employees.
responses:
200:
description: Return all employees from the database.
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Employee"
components:
schemas:
Employee:
"$ref": "https://raw.githubusercontent.com/jdkandersson/OpenAlchemy/master/examples/remote/remote-example-spec.yml#/Employee"
|
For a schema to be picked up by OpenAlchemy, it must have an entry in the #/components/schemas/… object. Remote references from within a schema are also supported.