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

  1. another file within the file system and

  2. a file available at a URL.

Warning

  1. 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.