Merge pull request #57 from OAI/draft-version-minor-enrichment

Components Section for reusability

README.md

@@ -39,6 +39,7 @@ The current SIG is made up of the following individuals, and feel free to submit
 - Mark Haine ([Founder, Considrd Consulting](https://www.linkedin.com/in/mark-haine/))
 - Phil Sturgeon ([Dev Rel, Stoplight](https://www.linkedin.com/in/philipsturgeon/))
 - Kevin Duffey ([Tech Lead, Postman](https://www.linkedin.com/in/kmd/))
+- Shai Sachs ([Staff Engineer, Chewy](https://linkedin.com/in/shaisachs/))
 
 ## The Workflows Specification
 

examples/1.0.0/FAPI-PAR.workflow.yaml

@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: >-
     A workflow describing how to obtain a token from an OAuth2 and OpenID Connect Financial Grade authorization server which can be common for PSD2 API journeys
-sources:
+sourceDocuments:
   - name: auth-api
     url: ./FAPI-PAR.openapi.yaml
     type: openapi

examples/1.0.0/LoginAndRetrievePets.yaml

@@ -5,7 +5,7 @@ info:
     description: |
         This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
     version: 1.0.1
-sources:
+sourceDocuments:
 - name: petStoreDefinition
   url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
   type: openapi

examples/1.0.0/oauth.workflow.yaml

@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: >-
     APImetrics OAuth service
-sources:
+sourceDocuments:
   - name: apim-auth
     url: ./oauth.openapi.yaml
     type: openapi
@@ -37,9 +37,6 @@ workflows:
         #   # Or a previous refresh-token-flow.outputs.refresh_token
     steps:
       - stepId: do-the-auth-flow
-        # Open question: how do we reference a workflow from another file?
-        # e.g.: 
-        # workflowId: $sources.sample.workflows.authorization-code-flow
         workflowId: authorization-code-flow
         parameters:
         - name: client_id

examples/1.0.0/pet-coupons.openapi.yaml

@@ -113,6 +113,19 @@ paths:
               - available
               - pending
               - sold
+        - name: page
+          in: query
+          description: Which page of results to display. First page is 1.
+          required: true
+          schema:
+            type: int32
+        - name: pageSize
+          in: query
+          description: Number of results to display per page.
+          required: false
+          schema:
+            type: int32
+            default: 10
       responses:
         '200':
           description: successful operation

examples/1.0.0/pet-coupons.workflow.yaml

@@ -6,7 +6,7 @@ info:
     Illustrates a workflow whereby a client a) finds a pet in the petstore, 
     b) finds coupons for that pet, and finally
     c) orders the pet while applying the coupons from step b.
-sources:
+sourceDocuments:
   - name: pet-coupons
     url: ./pet-coupons.openapi.yaml
     type: openapi
@@ -17,13 +17,7 @@ workflows:
       This is how you can find a pet, find an applicable coupon, and apply that coupon in your order.
       The workflow concludes by outputting the ID of the placed order.
     inputs:
-      type: object
-      properties:
-        my_pet_tags:
-          type: array
-          items:
-            type: string
-          description: Desired tags to use when searching for a pet, in CSV format: e.g. "puppy, dalmation"
+      $ref: "#/components/inputs/apply_coupon_input"
     steps:
       - stepId: find-pet
         operationId: findPetsByTags
@@ -50,21 +44,83 @@ workflows:
         outputs:
           my_coupon_code: $response.body.couponCode
       - stepId: place-order
-        description: Use the coupon to get a discount on the desired pet.
+        workflowId: place-order
+        parameters:
+          - name: pet_id
+            in: body
+            value: $steps.find-pet.outputs.my_pet_id
+          - name: coupon_code
+            in: body
+            value: $steps.find-coupons.outputs.my_coupon_code
+        successCriteria:
+          - $statusCode == 200
+        outputs:
+          my_order_id: $response.body.id
+  - workflowId: buy-available-pet
+    summary: Buy an available pet if one is available.
+    description:
+      This workflow demonstrates a workflow very similar to `apply-coupon`, by intention.
+      It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`).
+    inputs:
+      $ref: "#/components/inputs/buy_available_pet_input"
+    steps:
+      - stepId: find-pet
+        operationId: findPetsByStatus
+        parameters:
+          - name: status
+            in: query
+            value: "available"
+          - $ref: '#/components/parameters/page'
+            value: 1
+          - $ref: '#/components/parameters/pageSize'
+            value: 10
+        successCriteria:
+          - $statusCode == 200
+        outputs:
+          my_pet_id: $outputs[0].id
+      - stepId: place-order
+        workflowId: place-order
+        parameters:
+          - name: pet_id
+            in: body
+            value: $steps.find-pet.outputs.my_pet_id
+        successCriteria:
+          - $statusCode == 200
+        outputs:
+          my_order_id: $response.body.id
+  - workflowId: place-order
+    summary: Place an order for a pet.
+    description:
+      This workflow places an order for a pet. It may be reused by other workflows as the "final step" in a purchase.
+    inputs:
+      type: object
+      properties:
+        pet_id:
+          type: integer
+          format: int64
+          description: The ID of the pet to place in the order.
+        quantity:
+          type: integer
+          format: int32
+          description: The number of pets to place in the order.
+        coupon_code:
+          type: string
+          description: The coupon code to apply to the order.
+    steps:
+      - stepId: place-order
         operationId: placeOrder
         parameters:
           - name: pet_id
             in: body
             target: $request.body#/petId
-            value: $steps.find-pet.outputs.my_pet_id
+            value: $inputs.pet_id
           - name: coupon_code
             in: body
             target: $request.body#/couponCode
-            value: $steps.find-pet.outputs.my_coupon_code
+            value: $inputs.coupon_code
           - name: quantity
             in: body
-            target: $request.body#/quantity
-            value: 1
+            value: $inputs.quantity
           - name: status
             in: body
             target: $request.body#/status
@@ -77,7 +133,30 @@ workflows:
           - $statusCode == 200
         outputs:
           my_order_id: $response.body.id
-
-
-    outputs:
-      order_id: $steps.place-order.my_order_id
+components:
+  inputs:
+    apply_coupon_input:
+      type: object
+      properties:
+        my_pet_tags:
+          type: array
+          items:
+            type: string
+          description: Desired tags to use when searching for a pet, in CSV format (e.g. "puppy, dalmatian")
+        store_id:
+          $ref: "#/components/inputs/store_id"
+    buy_available_pet_input:
+      type: object
+      properties:
+        store_id:
+          $ref: "#/components/inputs/store_id"
+    store_id:
+      type: string
+      description: Indicates the domain name of the store where the customer is browsing or buying pets, e.g. "pets.example.com" or "pets.example.co.uk".
+  parameters:
+    page:
+      type: integer
+      format: int32
+    pageSize:
+      type: integer
+      format: int32