docs(other): respect usage article

learn/arazzo/_filesets/practical-example-series/contract-testing/redocly-cafe-api.arazzo.yaml

@@ -0,0 +1,35 @@
+arazzo: 1.0.1
+info:
+  title: Redocly Cafe API - Products
+  version: 1.0.0
+  description: This is a test suite for the Redocly Cafe API.
+# @chunk {"steps": ["arazzo-source-descriptions"]}
+sourceDescriptions:
+  - name: redocly-cafe-api
+    type: openapi
+    url: redocly-cafe-api.yaml
+# @chunk-end
+
+# @chunk {"steps": ["arazzo-workflows"]}
+workflows:
+  - workflowId: menu-items-workflow
+    summary: Menu Items Workflow
+    # @chunk {"steps": ["arazzo-steps"]}
+    steps:
+      - stepId: get-products
+        # @chunk {"steps": ["arazzo-operation-id", "arazzo-step-operation"]}
+        operationId: $sourceDescriptions.redocly-cafe-api.listMenuItems
+        # @chunk-end
+        description: This step gets all products.
+        # @chunk {"steps": ["arazzo-parameters"]}
+        parameters:
+          - in: query
+            name: limit
+            value: 1
+        # @chunk-end
+        # @chunk {"steps": ["arazzo-success-criteria"]}
+        successCriteria:
+          - condition: $statusCode == 200
+        # @chunk-end
+    # @chunk-end
+# @chunk-end

learn/arazzo/_filesets/practical-example-series/contract-testing/redocly-cafe-api.yaml

@@ -0,0 +1,209 @@
+openapi: 3.1.0
+info:
+  title: Redocly Cafe
+  version: 1.0.0
+  contact:
+    email: team@redocly.com
+    url: https://redocly.com/contact-us/
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  termsOfService: https://redocly.com/subscription-agreement
+servers:
+  - url: https://cafe.cloud.redocly.com
+    description: Live server.
+tags:
+  - name: Products
+    description: Operations related to products.
+paths:
+  # @chunk {"steps": ["openapi-list-menu-items", "arazzo-step-operation"]}
+  /menu:
+    get:
+      tags:
+        - Products
+      summary: List all menu items
+      operationId: listMenuItems
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+      responses:
+        '200':
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MenuItemList'
+        '400':
+          description: Bad request - invalid input parameters.
+        '500':
+          description: Internal server error.
+  # @chunk-end
+components:
+  parameters:
+    Limit:
+      name: limit
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+      example: 10
+  schemas:
+    Page:
+      type: object
+      properties:
+        endCursor:
+          type:
+            - string
+            - 'null'
+        startCursor:
+          type:
+            - string
+            - 'null'
+        hasNextPage:
+          type: boolean
+        hasPrevPage:
+          type: boolean
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 10
+        total:
+          type: integer
+          minimum: 0
+      required:
+        - endCursor
+        - startCursor
+        - hasNextPage
+        - hasPrevPage
+        - limit
+        - total
+    MenuBaseItem:
+      type: object
+      properties:
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
+        id:
+          type: string
+          readOnly: true
+          pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
+        object:
+          type: string
+          const: menuItem
+          readOnly: true
+        name:
+          type: string
+          minLength: 1
+          maxLength: 50
+        price:
+          type: integer
+          minimum: 0
+        photo:
+          writeOnly: true
+          type:
+            - string
+            - 'null'
+          format: binary
+        photoUrl:
+          readOnly: true
+          type: string
+          format: uri
+        photoTextDescription:
+          type:
+            - string
+            - 'null'
+      required:
+        - id
+        - name
+        - price
+        - createdAt
+        - updatedAt
+        - object
+    Beverage:
+      allOf:
+        - type: object
+          properties:
+            category:
+              type: string
+              const: beverage
+            volume:
+              type: number
+              exclusiveMinimum: 0
+            containsCaffeine:
+              type: boolean
+        - $ref: '#/components/schemas/MenuBaseItem'
+    Dessert:
+      allOf:
+        - type: object
+          properties:
+            category:
+              type: string
+              const: dessert
+            calories:
+              type: number
+              exclusiveMinimum: 0
+        - $ref: '#/components/schemas/MenuBaseItem'
+    MenuItem:
+      discriminator:
+        propertyName: category
+        mapping:
+          beverage: '#/components/schemas/Beverage'
+          dessert: '#/components/schemas/Dessert'
+      oneOf:
+        - $ref: '#/components/schemas/Beverage'
+        - $ref: '#/components/schemas/Dessert'
+      required:
+        - category
+    # @chunk {"steps": ["openapi-broken-schema", "schema-failure", "schema-fix"]}
+    MenuItemList:
+      type: array
+      items:
+        type: object
+        properties:
+          object:
+            type: string
+            const: list
+          page:
+            $ref: '#/components/schemas/Page'
+          items:
+            type: array
+            items:
+              $ref: '#/components/schemas/MenuItem'
+        required:
+          - object
+          - page
+          - items
+    # @chunk-end
+    Error:
+      type: object
+      properties:
+        type:
+          type: string
+          format: uri-reference
+          default: about:blank
+        title:
+          type: string
+        status:
+          type: integer
+          format: int32
+          minimum: 100
+          exclusiveMaximum: 600
+        instance:
+          type: string
+          format: uri-reference
+        details:
+          type: object
+          additionalProperties: true
+      required:
+        - type
+        - title
+        - status

learn/arazzo/_filesets/practical-example-series/oauth2/authorization.arazzo.yaml

@@ -0,0 +1,60 @@
+arazzo: 1.0.1
+info:
+  title: Redocly Cafe API - Authorization
+  version: 1.0.0
+  description: This is the API for the Redocly Cafe OAuth2 client registration.
+# @chunk {"steps": ["auth-sources"]}
+sourceDescriptions:
+  - name: redocly-cafe-api
+    type: openapi
+    url: redocly-cafe-api.yaml
+  # @chunk {"steps": ["auth-source-arazzo"]}
+  - name: register-oauth2
+    type: arazzo
+    url: register-oauth2-client.arazzo.yaml
+  # @chunk-end
+# @chunk-end
+
+workflows:
+  - workflowId: authorize-with-client_credentials
+    summary: Authorize a new OAuth2 client
+    steps:
+      # @chunk {"steps": ["auth-step-reuse"]}
+      - stepId: register-oauth2-client
+        description: This step registers a new OAuth2 client.
+        workflowId: $sourceDescriptions.register-oauth2.workflows.register-oauth2-client-workflow
+        outputs:
+          clientId: $outputs.clientId
+          clientSecret: $outputs.clientSecret
+      # @chunk-end
+      # @chunk {"steps": ["auth-step-token"]}
+      - stepId: authorize-with-client_credentials
+        # @chunk {"steps": ["auth-x-operation"]}
+        x-operation:
+          method: POST
+          url: https://cafe.cloud.redocly.com/oauth2/token
+        # @chunk-end
+        parameters:
+          - in: header
+            name: content-type
+            value: application/x-www-form-urlencoded
+        # @chunk {"steps": ["auth-token-request-body"]}
+        requestBody:
+          payload:
+            grant_type: client_credentials
+            client_id: $steps.register-oauth2-client.outputs.clientId
+            client_secret: $steps.register-oauth2-client.outputs.clientSecret
+        # @chunk-end
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.body#/access_token != null
+        # @chunk {"steps": ["auth-token-output"]}
+        outputs:
+          access_token: $response.body#/access_token
+        # @chunk-end
+      # @chunk-end
+    # @chunk {"steps": ["auth-workflow-outputs"]}
+    outputs:
+      access_token_with_client_credentials: $steps.authorize-with-client_credentials.outputs.access_token
+      client_id: $steps.register-oauth2-client.outputs.clientId
+    # @chunk-end

learn/arazzo/_filesets/practical-example-series/oauth2/redocly-cafe-api.arazzo.yaml

@@ -0,0 +1,66 @@
+arazzo: 1.0.1
+info:
+  title: Redocly Cafe API - Products
+  version: 1.0.0
+  description: This is the API for the Redocly Cafe Products.
+# @chunk {"steps": ["final-sources"]}
+sourceDescriptions:
+  - name: redocly-cafe-api
+    type: openapi
+    url: redocly-cafe-api.yaml
+  - name: authorization
+    type: arazzo
+    url: authorization.arazzo.yaml
+# @chunk-end
+
+workflows:
+  - workflowId: menu-items-workflow
+    summary: Menu Items Workflow
+    steps:
+      # @chunk {"steps": ["final-step-authorize"]}
+      - stepId: authorize
+        workflowId: $sourceDescriptions.authorization.workflows.authorize-with-client_credentials
+        outputs:
+          access_token: $outputs.access_token_with_client_credentials
+          client_id: $outputs.client_id
+      # @chunk-end
+      # @chunk {"steps": ["final-step-create"]}
+      - stepId: create-menu-item
+        operationId: $sourceDescriptions.redocly-cafe-api.createMenuItem
+        description: This step creates a new menu item.
+        # @chunk {"steps": ["final-x-security"]}
+        x-security:
+          - schemeName: OAuth2
+            values:
+              accessToken: $steps.authorize.outputs.access_token
+              clientId: $steps.authorize.outputs.client_id
+        # @chunk-end
+        # @chunk {"steps": ["final-create-body"]}
+        requestBody:
+          contentType: multipart/form-data
+          payload:
+            name: $faker.string.uuid()
+            price: 4000
+            calories: 8000
+            category: 'dessert'
+            photoTextDescription: 'this is a tiramisu'
+        # @chunk-end
+        successCriteria:
+          - condition: $statusCode == 201
+          - condition: $response.body#/id != null
+        outputs:
+          menuItemId: $response.body#/id
+          name: $response.body#/name
+      # @chunk-end
+      # @chunk {"steps": ["final-step-verify"]}
+      - stepId: verify-menu-item
+        operationId: $sourceDescriptions.redocly-cafe-api.listMenuItems
+        description: This to verify created menu item
+        parameters:
+          - in: query
+            name: filter
+            value: 'name:{$steps.create-menu-item.outputs.name}'
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.body#/items/0/name == $steps.create-menu-item.outputs.name
+      # @chunk-end