The core elements are now all in and all tests are passing. Locking in v0.0.1

Signed-off-by: Dave Shanley <dave@quobix.com>

index/spec_index_test.go

@@ -43,7 +43,7 @@ func TestSpecIndex_ExtractRefsStripe(t *testing.T) {
 
 func TestSpecIndex_Asana(t *testing.T) {
 
-    asana, _ := ioutil.ReadFile("test_files/asana.yaml")
+    asana, _ := ioutil.ReadFile("../test_specs/asana.yaml")
     var rootNode yaml.Node
     yaml.Unmarshal(asana, &rootNode)
 
@@ -66,7 +66,7 @@ func TestSpecIndex_Asana(t *testing.T) {
 
 func TestSpecIndex_k8s(t *testing.T) {
 
-    asana, _ := ioutil.ReadFile("test_files/k8s.json")
+    asana, _ := ioutil.ReadFile("../test_specs/k8s.json")
     var rootNode yaml.Node
     yaml.Unmarshal(asana, &rootNode)
 
@@ -93,7 +93,7 @@ func TestSpecIndex_k8s(t *testing.T) {
 
 func TestSpecIndex_PetstoreV2(t *testing.T) {
 
-    asana, _ := ioutil.ReadFile("test_files/petstorev2.json")
+    asana, _ := ioutil.ReadFile("../test_specs/petstorev2.json")
     var rootNode yaml.Node
     yaml.Unmarshal(asana, &rootNode)
 
@@ -117,7 +117,7 @@ func TestSpecIndex_PetstoreV2(t *testing.T) {
 
 func TestSpecIndex_XSOAR(t *testing.T) {
 
-    xsoar, _ := ioutil.ReadFile("test_files/xsoar.json")
+    xsoar, _ := ioutil.ReadFile("../test_specs/xsoar.json")
     var rootNode yaml.Node
     yaml.Unmarshal(xsoar, &rootNode)
 
@@ -136,7 +136,7 @@ func TestSpecIndex_XSOAR(t *testing.T) {
 
 func TestSpecIndex_PetstoreV3(t *testing.T) {
 
-    asana, _ := ioutil.ReadFile("test_files/petstorev3.json")
+    asana, _ := ioutil.ReadFile("../test_specs/petstorev3.json")
     var rootNode yaml.Node
     yaml.Unmarshal(asana, &rootNode)
 
@@ -164,7 +164,7 @@ func TestSpecIndex_PetstoreV3(t *testing.T) {
 
 func TestSpecIndex_BurgerShop(t *testing.T) {
 
-    burgershop, _ := ioutil.ReadFile("test_files/burgershop.openapi.yaml")
+    burgershop, _ := ioutil.ReadFile("../test_specs/burgershop.openapi.yaml")
     var rootNode yaml.Node
     yaml.Unmarshal(burgershop, &rootNode)
 
@@ -234,7 +234,7 @@ func TestSpecIndex_BurgerShop(t *testing.T) {
 
 func TestSpecIndex_BurgerShop_AllTheComponents(t *testing.T) {
 
-    burgershop, _ := ioutil.ReadFile("test_files/all-the-components.yaml")
+    burgershop, _ := ioutil.ReadFile("../test_specs/all-the-components.yaml")
     var rootNode yaml.Node
     yaml.Unmarshal(burgershop, &rootNode)
 
@@ -311,7 +311,7 @@ func TestSpecIndex_NoRoot(t *testing.T) {
 
 func TestSpecIndex_BurgerShopMixedRef(t *testing.T) {
 
-    spec, _ := ioutil.ReadFile("test_files/mixedref-burgershop.openapi.yaml")
+    spec, _ := ioutil.ReadFile("../test_specs/mixedref-burgershop.openapi.yaml")
     var rootNode yaml.Node
     yaml.Unmarshal(spec, &rootNode)
 
@@ -335,7 +335,7 @@ func TestSpecIndex_BurgerShopMixedRef(t *testing.T) {
 
 func TestSpecIndex_TestEmptyBrokenReferences(t *testing.T) {
 
-    asana, _ := ioutil.ReadFile("test_files/badref-burgershop.openapi.yaml")
+    asana, _ := ioutil.ReadFile("../test_specs/badref-burgershop.openapi.yaml")
     var rootNode yaml.Node
     yaml.Unmarshal(asana, &rootNode)
 

test_specs/all-the-components.yaml

@@ -0,0 +1,371 @@
+openapi: 3.0.1
+info:
+  title: Burger Shop
+  description: |
+    The best burger API at quobix. You can find the testiest burgers on the world
+  termsOfService: https://quobix.com
+  contact:
+    name: quobix
+  license:
+    name: Quobix
+  version: "1.2"
+tags:
+  - name: "pizza"
+    description: pizza!
+    externalDocs:
+      description: "Find out more"
+      url: "https://quobix.com/"
+  - name: "Dressing"
+    description: "Variety of dressings: cheese, veggie, oil and a lot more"
+    externalDocs:
+      description: "Find out more information about our products)"
+      url: "https://quobix.com/"
+servers:
+  - url: https://quobix.com/api
+  - url: https://pb33f.com/api
+paths:
+  /burgers:
+    servers:
+      - url: https://somwhere.quobix.com/api
+      - url: https://pb33f.io/api
+    post:
+      operationId: createBurger
+      tags:
+        - "Meat"
+      summary:  Create a new burger
+      description: A new burger for our menu, yummy yum yum.
+      requestBody:
+        description: Give us the new burger!
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Burger'
+            examples:
+              pbjBurger:
+                summary: A horrible, nutty, sticky mess.
+                value:
+                  name: Peanut And Jelly
+                  numPatties: 3
+              cakeBurger:
+                summary: A sickly, sweet, atrocity
+                value:
+                  name: Chocolate Cake Burger
+                  numPatties: 5
+      responses:
+        "200":
+          description: A tasty burger for you to eat.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Burger'
+              examples:
+                quarterPounder:
+                  summary: A juicy two handler sammich
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: A tasty treat from the sea
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            LocateBurger:
+              operationId: locateBurger
+              parameters:
+                burgerId: '$response.body#/id'
+              description: Go and get a tasty burger
+            AnotherLocateBurger:
+              operationId: locateBurger
+              parameters:
+                burgerId: '$response.body#/id'
+              description: Go and get a another really tasty burger
+        "500":
+          description: Unexpected error creating a new burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: oh my goodness
+                  value:
+                    message: something went terribly wrong my friend, no new burger for you.
+        "422":
+          description: Unprocessable entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: invalid request
+                  value:
+                    message: unable to accept this request, looks bad, missing something.
+  /burgers/{burgerId}:
+    get:
+      servers:
+        - url: https://nowhere.quobix.com/api
+        - url: https://pb33f.net/api
+      operationId: locateBurger
+      tags:
+        - "Meat"
+      summary: Search a burger by ID - returns the burger with that identifier
+      description: Look up a tasty burger take it and enjoy it
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the burger. use this to order your food
+          required: true
+      responses:
+        "200":
+          description: A tasty burger for you to eat. Wide variety of products to choose from
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Burger'
+              examples:
+                quarterPounder:
+                  summary: A juicy two handler sammich
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: A tasty treat from the sea
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            ListBurgerDressings:
+              operationId: listBurgerDressings
+              parameters:
+                dressingId: 'something here'
+              description: 'Try the ketchup!'
+        "404":
+          description: Cannot find your burger. Sorry. We may have sold out of this type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  $ref: '#/components/examples/notFound'
+        "500":
+          description: Unexpected error. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: oh my stars
+                  value:
+                    message: something went terribly wrong my friend, burger location crashed!
+  /burgers/{burgerId}/dressings:
+    get:
+      operationId: listBurgerDressings
+      tags:
+        - "Dressing"
+      summary:  Get a list of all dressings available
+      description: Same as the summary, look up a tasty burger, by its ID - the burger identifier
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the our fantastic burger. You can pick a name from our menu
+          required: true
+      callbacks:
+        myCallback:
+          $ref: '#/components/callbacks/myCallback'
+      responses:
+        "200":
+          links:
+            getBurger:
+              $ref: '#/components/links/getBurger'
+          description: an array of
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dressing'
+        "404":
+          description: Cannot find your burger in which to list dressings. Sorry
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "500":
+          description: Unexpected error listing dressings for burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /dressings/{dressingId}:
+    get:
+      operationId: getDressing
+      tags:
+        - "Dressing"
+      summary:  Get a specific dressing - you can choose the dressing from our menu
+      description: Same as the summary, get a dressing, by its ID
+      parameters:
+        - in: path
+          name: dressingId
+          schema:
+            type: string
+          example: cheese
+          description: This is the unique identifier for the dressing items.
+          required: true
+      responses:
+        "404":
+          description: Cannot find your dressing, sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "500":
+          description: Unexpected error getting a dressing. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /dressings:
+    get:
+      operationId: getAllDressings
+      tags:
+        - "Dressing"
+      summary:  Get all dressings available in our store
+      description: Get all dressings and choose from them
+      responses:
+        "200":
+          $ref: '#/components/responses/dressingResponse'
+        "500":
+          description: Unexpected error. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  responses:
+    dressingResponse:
+      description: an array of dressings
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/Dressing'
+  callbacks:
+    myCallback:
+      '{$request.query.queryUrl}':
+        post:
+          requestBody:
+            description: Callback payload
+            content:
+              'application/json':
+                schema:
+                  $ref: '#/components/schemas/Fries'
+          responses:
+            '200':
+              description: callback successfully processed
+  links:
+    burger:
+      operationId: getBurger
+      parameters:
+        burgerId: $request.path.id
+  headers:
+    MyHeader:
+      description: a header
+  examples:
+    notFound:
+      summary: burger missing
+      value:
+        message: can't find a burger with that ID, we may have sold out my friend.
+  schemas:
+    Error:
+      type: object
+      description: Error defining what went wrong when providing a specification. The message should help indicate the issue clearly.
+      properties:
+        message:
+          type: string
+          description: returns the error message if something wrong happens
+          example: No such burger as 'Big-Whopper'
+    Burger:
+      type: object
+      description: The tastiest food on the planet you would love to eat everyday
+      required:
+        - name
+        - numPatties
+      properties:
+        name:
+          type: string
+          description: The name of your tasty burger - burger names are listed in our menus
+          example: Big Mac
+        numPatties:
+          type: integer
+          description: The number of burger patties used
+          example: 2
+        numTomatoes:
+          type: integer
+          description: how many slices of orange goodness would you like?
+          example: 1
+    Fries:
+      type: object
+      description: golden slices of happy fun joy
+      required:
+        - potatoShape
+        - favoriteDressings
+        - favoriteDrink
+      properties:
+        seasoning:
+          type: array
+          description: herbs and spices for your golden joy
+          items:
+            type: string
+            description: type of herb or spice used to liven up the yummy
+            example: salt
+        potatoShape:
+          type: string
+          description: what type of potato shape? wedges? shoestring?
+          example: Crispy Shoestring
+        favoriteDressings:
+          type: array
+          items:
+            $ref: '#/components/schemas/Dressing'
+        favoriteBurger:
+          $ref: '#/components/schemas/Burger'
+        favoriteDrink:
+          $ref: '#/components/schemas/Drink'
+    Dressing:
+      type: object
+      description: This is the object that contains the information about the content of the dressing
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The name of your dressing you can pick up from the menu
+          example: Cheese
+    Drink:
+      type: object
+      description: a frosty cold beverage can be coke or sprite
+      required:
+        - size
+        - drinkType
+      properties:
+        ice:
+          type: boolean
+        drinkType:
+          description: select from coke or sprite
+          enum:
+            - coke
+            - sprite
+        size:
+          type: string
+          description: what size man? S/M/L
+          example: M

test_specs/badref-burgershop.openapi.yaml

@@ -0,0 +1,326 @@
+openapi: 3.0.1
+info:
+  title: Burger Shop
+  description: |
+    The best burger API at quobix. You can find the testiest burgers on the world
+  termsOfService: https://quobix.com
+  contact:
+    name: quobix
+  license:
+    name: Quobix
+  version: "1.2"
+tags:
+  - name: "pizza"
+    description: false
+    externalDocs:
+      description: "Find out more"
+      url: "https://quobix.com/"
+  - name: "Dressing"
+    description: "Variety of dressings: cheese, veggie, oil and a lot more"
+    externalDocs:
+      description: "Find out more information about our products)"
+      url: "https://quobix.com/"
+servers:
+  - url: https://quobix.com/api
+paths:
+  /burgers:
+    post:
+      operationId: createBurger
+      tags:
+        - "Meat"
+      summary:  Create a new burger
+      description: A new burger for our menu, yummy yum yum.
+      requestBody:
+        description: Give us the new burger!
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Burgers'
+            examples:
+              pbjBurger:
+                summary: A horrible, nutty, sticky mess.
+                value:
+                  name: Peanut And Jelly
+                numPatties: 3
+              cakeBurger:
+                summary: A sickly, sweet, atrocity
+                value:
+                  name: Chocolate Cake Burger
+                  numPatties: 5
+      responses:
+        "200":
+          description: A tasty burger for you to eat.
+          content:
+            application/json:
+              schema:
+                $ref: ''
+              examples:
+                quarterPounder:
+                  summary: A juicy two handler sammich
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: A tasty treat from the sea
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            LocateBurger:
+              operationId: locateBurger
+              parameters:
+                burgerId: '$response.body#/id'
+              description: Go and get a tasty burger
+        "500":
+          description: Unexpected error creating a new burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: oh my goodness
+                  value:
+                    message: something went terribly wrong my friend, no new burger for you.
+        "422":
+          description: Unprocessable entity
+          content:
+            application/json:
+              schema:
+                $ref: 'http://go#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: invalid request
+                  value:
+                    message: unable to accept this request, looks bad, missing something.
+  /burgers/{burgerId}:
+    get:
+      operationId: locateBurger
+      tags:
+        - "Meat"
+      summary: Search a burger by ID - returns the burger with that identifier
+      description: Look up a tasty burger take it and enjoy it
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the burger. use this to order your food
+          required: true
+      responses:
+        "200":
+          description: A tasty burger for you to eat. Wide variety of products to choose from
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Burger'
+              examples:
+                quarterPounder:
+                  summary: A juicy two handler sammich
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: A tasty treat from the sea
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            ListBurgerDressings:
+              operationId: listBurgerDressings
+              parameters:
+                dressingId: 'something here'
+              description: 'Try the ketchup!'
+        "404":
+          description: Cannot find your burger. Sorry. We may have sold out of this type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  summary: burger missing
+                  value:
+                    message: can't find a burger with that ID, we may have sold out my friend.
+        "500":
+          description: Unexpected error. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: ''
+              examples:
+                unexpectedError:
+                  summary: oh my stars
+                  value:
+                    message: something went terribly wrong my friend, burger location crashed!
+  /burgers/{burgerId}/dressings:
+    get:
+      operationId: listBurgerDressings
+      tags:
+        - "Dressing"
+      summary:  Get a list of all dressings available
+      description: Same as the summary, look up a tasty burger, by its ID - the burger identifier
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the our fantastic burger. You can pick a name from our menu
+          required: true
+      responses:
+        "200":
+          description: an array of
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dressing'
+        "404":
+          description: Cannot find your burger in which to list dressings. Sorry
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "500":
+          description: Unexpected error listing dressings for burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /dressings/{dressingId}:
+    get:
+      operationId: getDressing
+      tags:
+        - "Dressing"
+      summary:  Get a specific dressing - you can choose the dressing from our menu
+      description: Same as the summary, get a dressing, by its ID
+      parameters:
+        - in: path
+          name: dressingId
+          schema:
+            type: string
+          example: cheese
+          description: This is the unique identifier for the dressing items.
+          required: true
+      responses:
+        "404":
+          description: Cannot find your dressing, sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "500":
+          description: Unexpected error getting a dressing. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Errors'
+  /dressings:
+    get:
+      operationId: getAllDressings
+      tags:
+        - "Dressing"
+      summary:  Get all dressings available in our store
+      description: Get all dressings and choose from them
+      responses:
+        "200":
+          description: an array of dressings
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dressing'
+        "500":
+          description: Unexpected error. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    Error:
+      type: object
+      description: Error defining what went wrong when providing a specification. The message should help indicate the issue clearly.
+      properties:
+        message:
+          type: string
+          description: returns the error message if something wrong happens
+          example: No such burger as 'Big-Whopper'
+    Burger:
+      type: object
+      description: The tastiest food on the planet you would love to eat everyday
+      required:
+        - name
+        - numPatties
+      properties:
+        name:
+          type: string
+          description: The name of your tasty burger - burger names are listed in our menus
+          example: Big Mac
+        numPatties:
+          type: integer
+          description: The number of burger patties used
+          example: 2
+        numTomatoes:
+          type: integer
+          description: how many slices of orange goodness would you like?
+          example: 1
+    Fries:
+      type: object
+      description: golden slices of happy fun joy
+      required:
+        - potatoShape
+        - favoriteDressings
+        - favoriteDrink
+      properties:
+        seasoning:
+          type: array
+          description: herbs and spices for your golden joy
+          items:
+            type: string
+            description: type of herb or spice used to liven up the yummy
+            example: salt
+        potatoShape:
+          type: string
+          description: what type of potato shape? wedges? shoestring?
+          example: Crispy Shoestring
+        favoriteDressings:
+          type: array
+          items:
+            $ref: '#/components/schemas/NotHere'
+        favoriteBurger:
+          $ref: '#/components/schemas/Burger'
+        favoriteDrink:
+          $ref: '#/components/schemas/Drink'
+    Dressing:
+      type: object
+      description: This is the object that contains the information about the content of the dressing
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The name of your dressing you can pick up from the menu
+          example: Cheese
+    Drink:
+      type: object
+      description: a frosty cold beverage can be coke or sprite
+      required:
+        - size
+        - drinkType
+      properties:
+        ice:
+          type: boolean
+        drinkType:
+          description: select from coke or sprite
+          enum:
+            - coke
+            - sprite
+        size:
+          type: string
+          description: what size man? S/M/L
+          example: M

test_specs/burgershop.openapi.yaml

@@ -0,0 +1,356 @@
+openapi: 3.0.1
+info:
+  title: Burger Shop
+  description: |
+    The best burger API at quobix. You can find the testiest burgers on the world
+  termsOfService: https://quobix.com
+  contact:
+    name: quobix
+  license:
+    name: Quobix
+  version: "1.2"
+tags:
+  - name: "Burgers"
+    description: "All kinds of yummy burgers."
+    externalDocs:
+      description: "Find out more"
+      url: "https://quobix.com/"
+  - name: "Dressing"
+    description: "Variety of dressings: cheese, veggie, oil and a lot more"
+    externalDocs:
+      description: "Find out more information about our products)"
+      url: "https://quobix.com/"
+servers:
+  - url: https://quobix.com/api
+paths:
+  /burgers:
+    post:
+      operationId: createBurger
+      tags:
+        - "Burgers"
+      summary:  Create a new burger
+      description: A new burger for our menu, yummy yum yum.
+      requestBody:
+        description: Give us the new burger!
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Burger'
+            examples:
+              pbjBurger:
+                summary: A horrible, nutty, sticky mess.
+                value:
+                  name: Peanut And Jelly
+                  numPatties: 3
+              cakeBurger:
+                summary: A sickly, sweet, atrocity
+                value:
+                  name: Chocolate Cake Burger
+                  numPatties: 5
+      responses:
+        "200":
+          description: A tasty burger for you to eat.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Burger'
+              examples:
+                quarterPounder:
+                  summary: a yummy tasty two patty burger, filled with beefy goodness.
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: a cripsy fish sammich filled with ocean goodness.
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            LocateBurger:
+              operationId: locateBurger
+              parameters:
+                burgerId: '$response.body#/id'
+              description: Go and get a tasty burger
+            AnotherLocateBurger:
+              operationId: locateBurger
+              parameters:
+                burgerId: '$response.body#/id'
+              description: Go and get a another really tasty burger
+        "500":
+          description: Unexpected error creating a new burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: oh my goodness
+                  value:
+                    message: something went terribly wrong my friend, no new burger for you.
+        "422":
+          description: Unprocessable entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: invalid request
+                  value:
+                    message: unable to accept this request, looks bad, missing something.
+  /burgers/{burgerId}:
+    get:
+      operationId: locateBurger
+      tags:
+        - "Burgers"
+      summary: Search a burger by ID - returns the burger with that identifier
+      description: Look up a tasty burger take it and enjoy it
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the burger. use this to order your food
+          required: true
+      responses:
+        "200":
+          description: A tasty burger for you to eat. Wide variety of products to choose from
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Burger'
+              examples:
+                quarterPounder:
+                  summary: A juicy two handler sammich
+                  value:
+                    name: Quarter Pounder with Cheese
+                    numPatties: 1
+                filetOFish:
+                  summary: A tasty treat from the sea
+                  value:
+                    name: Filet-O-Fish
+                    numPatties: 1
+          links:
+            ListBurgerDressings:
+              operationId: listBurgerDressings
+              parameters:
+                dressingId: 'something here'
+              description: 'Try the ketchup!'
+        "404":
+          description: Cannot find your burger. Sorry. We may have sold out of this type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  summary: burger missing
+                  value:
+                    message: can't find a burger with that ID, we may have sold out my friend.
+        "500":
+          description: Unexpected error. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unexpectedError:
+                  summary: oh my stars
+                  value:
+                    message: something went terribly wrong my friend, burger location crashed!
+  /burgers/{burgerId}/dressings:
+    get:
+      operationId: listBurgerDressings
+      tags:
+        - "Dressing"
+      summary:  Get a list of all dressings available
+      description: Same as the summary, look up a tasty burger, by its ID - the burger identifier
+      parameters:
+        - in: path
+          name: burgerId
+          schema:
+            type: string
+          example: big-mac
+          description: the name of the our fantastic burger. You can pick a name from our menu
+          required: true
+      responses:
+        "200":
+          description: all the dressings for a burger.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dressing'
+              example:
+                - name: Thousand Island
+        "404":
+          description: Cannot find your burger in which to list dressings. Sorry
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: There is no burger here
+        "500":
+          description: Unexpected error listing dressings for burger. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: computer says no dressings for this burger.
+  /dressings/{dressingId}:
+    get:
+      operationId: getDressing
+      tags:
+        - "Dressing"
+      summary:  Get a specific dressing - you can choose the dressing from our menu
+      description: Same as the summary, get a dressing, by its ID
+      parameters:
+        - in: path
+          name: dressingId
+          schema:
+            type: string
+          example: cheese
+          description: This is the unique identifier for the dressing items.
+          required: true
+      responses:
+        "200":
+          description: a dressing
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dressing'
+              example:
+                name: Butter Sauce
+        "404":
+          description: Cannot find your dressing, sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: No such dressing as 'Pizza'
+        "500":
+          description: Unexpected error getting a dressing. Sorry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: failed looking up dressing by ID, our server borked.
+  /dressings:
+    get:
+      operationId: getAllDressings
+      tags:
+        - "Dressing"
+      summary:  Get all dressings available in our store
+      description: Get all dressings and choose from them
+      responses:
+        "200":
+          description: an array of dressings
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dressing'
+              example:
+                - name: Burger Sauce
+        "418":
+          description: I am a teapot.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: It's teapot time.
+        "500":
+          description: Something went wrong with getting dressings.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                message: "failed looking up all dressings, something went wrong."
+components:
+  schemas:
+    Error:
+      type: object
+      description: Error defining what went wrong when providing a specification. The message should help indicate the issue clearly.
+      properties:
+        message:
+          type: string
+          description: returns the error message if something wrong happens
+          example: No such burger as 'Big-Whopper'
+    Burger:
+      type: object
+      description: The tastiest food on the planet you would love to eat everyday
+      required:
+        - name
+        - numPatties
+      properties:
+        name:
+          type: string
+          description: The name of your tasty burger - burger names are listed in our menus
+          example: Big Mac
+        numPatties:
+          type: integer
+          description: The number of burger patties used
+          example: 2
+        numTomatoes:
+          type: integer
+          description: how many slices of orange goodness would you like?
+          example: 1
+        fries:
+          $ref: '#/components/schemas/Fries'
+    Fries:
+      type: object
+      description: golden slices of happy fun joy
+      required:
+        - potatoShape
+        - favoriteDrink
+      properties:
+        seasoning:
+          type: array
+          description: herbs and spices for your golden joy
+          items:
+            type: string
+            description: type of herb or spice used to liven up the yummy
+            example: salt
+        potatoShape:
+          type: string
+          description: what type of potato shape? wedges? shoestring?
+          example: Crispy Shoestring
+        favoriteDrink:
+          $ref: '#/components/schemas/Drink'
+    Dressing:
+      type: object
+      description: This is the object that contains the information about the content of the dressing
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The name of your dressing you can pick up from the menu
+          example: Cheese
+    Drink:
+      type: object
+      description: a frosty cold beverage can be coke or sprite
+      required:
+        - size
+        - drinkType
+      properties:
+        ice:
+          type: boolean
+        drinkType:
+          description: select from coke or sprite
+          enum:
+            - coke
+            - sprite
+        size:
+          type: string
+          description: what size man? S/M/L
+          example: M

test_specs/mixedref-burgershop.openapi.yaml

@@ -166,7 +166,7 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: 'test_files/burgershop.openapi.yaml#/components/schemas/Dressing'
+                  $ref: '../test_specs/burgershop.openapi.yaml#/components/schemas/Dressing'
         "404":
           description: Cannot find your burger in which to list dressings. Sorry
           content:
@@ -222,7 +222,7 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: 'test_files/burgershop.openapi.yaml#/components/schemas/Dressing'
+                  $ref: '../test_specs/burgershop.openapi.yaml#/components/schemas/Dressing'
         "500":
           description: Unexpected error. Sorry.
           content: