Added prance as a dependency.

Connexion cannot currently handle $ref to external files.
prance merges OpenAPI files and dereferences $ref entries.
This works around connextions issue.
See for details: spec-first/connexion#254

Pipfile

@@ -19,6 +19,7 @@ connexion = {extras = ["swagger-ui"],version = "*"}
 flask = "*"
 python-dotenv = "*"
 rfc3987 = "*"
+prance = {extras = ["osv"],version = "*"}
 racecard = {editable = true,extras = ["rest"],path = "."}
 
 [requires]

racecard/server/rest/app.py

@@ -18,10 +18,14 @@
 """OpenAPI 3 RESTful web service application entry point."""
 
 
-from connexion import FlaskApp
+from pathlib import Path
+
+from connexion import App
 from connexion.resolver import Resolution, Resolver
+from prance import ResolvingParser
+from prance.util.resolver import RESOLVE_FILES, RESOLVE_HTTP
 
-app = FlaskApp(__name__, specification_dir="openapi/")
+app = App(__name__)
 
 
 class ImplicitPackageResolver(Resolver):
@@ -56,12 +60,25 @@ def resolve(self, operation):
         return Resolution(function, operation_id)
 
 
+def get_bundled_specs(main_file_path):
+    # Based on https://github.com/zalando/connexion/issues/254
+    parser = ResolvingParser(
+        str(Path(main_file_path).absolute()),
+        lazy=True,
+        strict=True,
+        backend="openapi-spec-validator",
+        resolve_types=RESOLVE_HTTP | RESOLVE_FILES,
+    )
+    parser.parse()
+    return parser.specification
+
+
 def main():
     app.add_api(
-        "openapi.yaml",
+        get_bundled_specs(Path(__file__).parent / "openapi" / "openapi.yaml"),
         strict_validation=True,
         validate_responses=True,
-        resolver=ImplicitPackageResolver("racecard.server.rest.api"),
+        resolver=ImplicitPackageResolver(__package__ + ".api"),
     )
     app.run()
 

racecard/server/rest/openapi/openapi.yaml

@@ -33,294 +33,11 @@ paths:
                 $ref: "#/components/schemas/gamesList"
 components:
   schemas:
-    response:
-      title: JSON:API Schema
-      description:
-        This is a schema for responses in the JSON:API format. For more, see
-        http://jsonapi.org
-      oneOf:
-        - $ref: "#/components/schemas/success"
-        - $ref: "#/components/schemas/failure"
-        - $ref: "#/components/schemas/info"
-    attributes:
-      type: object
-      # additionalProperties: false
-      description:
-        Members of the attributes object ("attributes") represent information
-        about the resource object in which it's defined.
-      # patternProperties:
-      #   ^(?!relationships$|links$|id$|type$)\w[-\w_]*$:
-      #     description: Attributes may contain any valid JSON value.
-    data:
-      description:
-        The document's "primary data" is a representation of the resource
-        or collection of resources targeted by a request.
-
-        null if the request is one that might correspond to a single resource,
-        but doesn't currently.
-      nullable: true
-      oneOf:
-        - $ref: "#/components/schemas/resource"
-        - type: array
-          uniqueItems: true
-          description:
-            An array of resource objects, an array of resource identifier objects,
-            or an empty array ([]), for requests that target resource collections.
-          items:
-            $ref: "#/components/schemas/resource"
-    error:
-      additionalProperties: false
-      properties:
-        code:
-          description: An application-specific error code, expressed as a string value.
-          type: string
-        detail:
-          description:
-            A human-readable explanation specific to this occurrence of the
-            problem.
-          type: string
-        id:
-          description: A unique identifier for this particular occurrence of the problem.
-          type: string
-        links:
-          $ref: "#/components/schemas/links"
-        meta:
-          $ref: "#/components/schemas/meta"
-        source:
-          properties:
-            parameter:
-              description: A string indicating which query parameter caused the error.
-              type: string
-            pointer:
-              description:
-                A JSON Pointer [RFC6901] to the associated entity in the
-                request document [e.g. "/data" for a primary data object, or "/data/attributes/title"
-                for a specific attribute].
-              type: string
-          type: object
-        status:
-          description:
-            The HTTP status code applicable to this problem, expressed as
-            a string value.
-          type: string
-        title:
-          description:
-            A short, human-readable summary of the problem. It **SHOULD NOT**
-            change from occurrence to occurrence of the problem, except for purposes
-            of localization.
-          type: string
-      type: object
-    failure:
-      additionalProperties: false
-      properties:
-        errors:
-          items:
-            $ref: "#/components/schemas/error"
-          type: array
-          uniqueItems: true
-        jsonapi:
-          $ref: "#/components/schemas/jsonapi"
-        links:
-          $ref: "#/components/schemas/links"
-        meta:
-          $ref: "#/components/schemas/meta"
-      required:
-        - errors
-      type: object
-    info:
-      additionalProperties: false
-      properties:
-        jsonapi:
-          $ref: "#/components/schemas/jsonapi"
-        links:
-          $ref: "#/components/schemas/links"
-        meta:
-          $ref: "#/components/schemas/meta"
-      required:
-        - meta
-      type: object
-    jsonapi:
-      additionalProperties: false
-      description: An object describing the server's implementation
-      properties:
-        meta:
-          $ref: "#/components/schemas/meta"
-        version:
-          type: string
-      type: object
-    link:
-      description:
-        "A link **MUST** be represented as either: a string containing the
-        link's URL or a link object."
-      oneOf:
-        - description: A string containing the link's URL.
-          format: uri-reference
-          type: string
-        - properties:
-            href:
-              description: A string containing the link's URL.
-              format: uri-reference
-              type: string
-            meta:
-              $ref: "#/components/schemas/meta"
-          required:
-            - href
-          type: object
-    linkage:
-      additionalProperties: false
-      description: The "type" and "id" to non-empty members.
-      properties:
-        id:
-          type: string
-        meta:
-          $ref: "#/components/schemas/meta"
-        type:
-          type: string
-      required:
-        - type
-        - id
-      type: object
-    links:
-      additionalProperties:
-        $ref: "#/components/schemas/link"
-      type: object
-    meta:
-      additionalProperties: true
-      description:
-        Non-standard meta-information that can not be represented as an attribute
-        or relationship.
-      type: object
-    pagination:
-      properties:
-        first:
-          description: The first page of data
-          type: string
-          format: uri-reference
-          nullable: true
-        last:
-          description: The last page of data
-          type: string
-          format: uri-reference
-          nullable: true
-        next:
-          description: The next page of data
-          type: string
-          format: uri-reference
-          nullable: true
-        prev:
-          description: The previous page of data
-          type: string
-          format: uri-reference
-          nullable: true
-      type: object
-    relationshipLinks:
-      additionalProperties: true
-      description:
-        A resource object **MAY** contain references to other resource objects
-        ("relationships"). Relationships may be to-one or to-many. Relationships can
-        be specified by including a member in a resource's links object.
-      properties:
-        related:
-          $ref: "#/components/schemas/link"
-        self:
-          $ref: "#/components/schemas/link"
-          description:
-            A `self` member, whose value is a URL for the relationship itself
-            (a "relationship URL"). This URL allows the client to directly manipulate
-            the relationship. For example, it would allow a client to remove an `author`
-            from an `article` without deleting the people resource itself.
-      type: object
-    relationshipToMany:
-      description:
-        An array of objects each containing "type" and "id" members for to-many
-        relationships.
-      items:
-        $ref: "#/components/schemas/linkage"
-      type: array
-      uniqueItems: true
-    relationshipToOne:
-      $ref: "#/components/schemas/linkage"
-      nullable: true
-      description:
-        References to other resource objects in a to-one ("relationship").
-        Relationships can be specified by including a member in a resource's links object.
-    relationships:
-      # additionalProperties: false
-      description:
-        Members of the relationships object ("relationships") represent references
-        from the resource object in which it's defined to other resource objects.
-      # patternProperties:
-      #   ^(?!id$|type$)\w[-\w_]*$:
-      #     additionalProperties: false
-      additionalProperties:
-        anyOf:
-          - required:
-              - data
-          - required:
-              - meta
-          - required:
-              - links
-        properties:
-          data:
-            description: Member, whose value represents "resource linkage".
-            oneOf:
-              - $ref: "#/components/schemas/relationshipToOne"
-              - $ref: "#/components/schemas/relationshipToMany"
-          links:
-            $ref: "#/components/schemas/relationshipLinks"
-          meta:
-            $ref: "#/components/schemas/meta"
-      type: object
-    resource:
-      additionalProperties: false
-      description: '"Resource objects" appear in a JSON:API document to represent resources.'
-      properties:
-        attributes:
-          $ref: "#/components/schemas/attributes"
-        id:
-          type: string
-        links:
-          $ref: "#/components/schemas/links"
-        meta:
-          $ref: "#/components/schemas/meta"
-        relationships:
-          $ref: "#/components/schemas/relationships"
-        type:
-          type: string
-      required:
-        - type
-        - id
-      type: object
-    success:
-      additionalProperties: false
-      properties:
-        data:
-          $ref: "#/components/schemas/data"
-        included:
-          description:
-            To reduce the number of HTTP requests, servers **MAY** allow
-            responses that include related resources along with the requested primary
-            resources. Such responses are called "compound documents".
-          items:
-            $ref: "#/components/schemas/resource"
-          type: array
-          uniqueItems: true
-        jsonapi:
-          $ref: "#/components/schemas/jsonapi"
-        links:
-          allOf:
-            - $ref: "#/components/schemas/links"
-            - $ref: "#/components/schemas/pagination"
-          description: Link members related to the primary data.
-        meta:
-          $ref: "#/components/schemas/meta"
-      required:
-        - data
-      type: object
-
     gamesList:
+      title: Games List
+      description: List of game IDs in JSON:API format.
       allOf:
-        - $ref: "#/components/schemas/response"
+        - $ref: "jsonapi_oas3.yaml#/components/schemas/response"
         - type: object
           properties:
             data: