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.