openapi.yaml

openapi: "3.0.3"
info:
  title: Sample E-commerce Application
  description: |-
    This is a ***Sample Ecommerce API*** based on the OpenAPI 3.0 specification.  You can find out more about
    Swagger at [https://swagger.io](https://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
    You can now help us improve the API whether it's by making changes to the definition itself or to the code.
    That way, with time, we can improve the API in general, and expose some of the new features in OAS3.

    
    Some useful links:
    - [The Cometbid-SFI repository](https://github.com/cometbid-sfi/swagger-ecommerce)
    - [The source API definition for the Ecommerce appliation](https://github.com/cometbid-sfi/swagger-ecommerce/blob/master/src/main/resources/openapi.yaml)
  termsOfService: https://github.com/cometbid-sfi/swagger-ecommerce/blob/main/LICENSE
  contact:
    name: The Cometbid Software Foundation Inc.
    url: http://www.cometbid.org
    email: support@cometbid.org
  license:
    name: MIT License
    url: https://github.com/cometbid-sfi/swagger-ecommerce/blob/main/LICENSE
  version: 1.0.0
externalDocs:
  description: Any document link you want to generate along with API.
  url: http://swagger.io
  
servers:
  - url: https://ecommerce.swagger.io/api/v1
tags:
  - name: cart
    description: Everything about Carts
    externalDocs:
      description: Find out more (extra document link)
      url: http://swagger.io
  - name: order
    description: Operations about orders
    externalDocs:
      description: Find out more about orders
      url: http://swagger.io
  - name: user
    description: Operations about users
  - name: store
    description: Operations about user's store orders
    externalDocs:
      description: Find out more about stores
      url: http://swagger.io
  - name: customer
    description: Operations about user's personal customer
  - name: address
    description: Operations about user's address
  - name: payment
    description: Operations about payments
  - name: shipping
    description: Operations about shippings
  - name: product
    description: Operations about products
  - name: card
    description: Card operations
  
paths:
  /api/v1/carts/{customerId}:
    get:
      tags:
        - cart
      summary: Returns the shopping cart
      description: Returns the shopping cart of given customer
      operationId: getCartByCustomerId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cart'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cart'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: Given Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'

    delete:
      tags:
        - cart
      summary: Delete the shopping cart
      description: Delete the shopping cart of given customer
      operationId: deleteCart
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '400':
          description: Bad Request 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: Given Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'

  /api/v1/carts/{customerId}/items:
    get:
      tags:
        - cart
      summary: Returns the list of products in user's shopping cart
      description: Returns the items in shopping cart of given customer
      operationId: getCartItemsByCustomerId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
        '404':
          description: Given Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    post:
      tags:
        - cart
      summary: Adds an item to a shopping cart
      description: Adds an item to the shopping cart if it doesn't exist, or increment quantity by the specified number of items if it does.
      operationId: addCartItemsByCustomerId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Item object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
          application/xml:
            schema:
              $ref: '#/components/schemas/Item'
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Item added successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'
        '404':
          description: Given Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    put:
      tags:
        - cart
      summary: Replace/add an item to a shopping cart
      description: Adds an item to the shopping cart if it doesn't exist, or replace with given item if it does.
      operationId: addOrReplaceItemsByCustomerId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Item object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
          application/xml:
            schema:
              $ref: '#/components/schemas/Item'
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Item added successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'
        '404':
          description: Given Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
          
  /api/v1/carts/{customerId}/items/{itemId}:
    get:
      tags:
        - cart
      summary: Returns given item from user's shopping cart
      description: Returns given item from shopping cart of given customer
      operationId: getCartItemsByItemId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: Item (product) Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation, if item exists in cart
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'
        '404':
          description: Given item (product) ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    delete:
      tags:
        - cart
      summary: Delete the item from shopping cart
      description: Deletes the item from shopping cart of given customer
      operationId: deleteItemFromCart
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: Item (product) Identifier
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepts the request, regardless of whether the specified item exists in the cart or not.
          content: {}
  /api/v1/orders:
    post:
      tags:
        - order
      summary: Creates a new order for the given order request
      description: Creates a new order for the given order request.
      operationId: addOrder
      requestBody:
        description: New order request object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
          application/xml:
            schema:
              $ref: '#/components/schemas/NewOrder'
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Order added successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '406':
          description: If payment is not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    get:
      tags:
        - order
      summary: Returns the orders of given user
      description: Returns the orders of given user
      operationId: getOrderByCustomerId
      parameters:
        - name: customerId
          in: query
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If order exists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'        
        '404':
          description: Order doesn't exist for given user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
  /api/v1/orders/{id}:
    get:
      tags:
        - order
      summary: Returns the order of given order ID
      description: Returns the orders of given order ID
      operationId: getOrdersByOrderId
      parameters:
        - name: id
          in: path
          description: Order Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If order exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'        
        '404':
          description: Order doesn't exist for given user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
  /api/v1/customers:
    post:
      tags:
        - customer
      summary: Returns all customers
      description: Returns all customers, or empty collection if no user found
      operationId: getAllCustomers
      responses:
        '200':
          description: For successful fetch
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /api/v1/customers/{id}:
    get:
      tags:
        - customer
      summary: Returns a customer
      description: Returns a customer identifiable by given ID
      operationId: getCustomerById
      parameters:
        - name: id
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'          
            application/xml:
              schema:
                $ref: '#/components/schemas/User'        
        '404':
          description: Customer not found by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    delete:
      tags:
        - customer
      summary: Deletes the customer
      description: Deletes the customer identifiable by given ID
      operationId: deleteCustomerById
      parameters:
        - name: id
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepts the request, returns this status even if user doesn't exist by the given id
          content: {}
          
  /api/v1/customers/{id}/cards:
    get:
      tags:
        - customer
      summary: Returns all customer's cards
      description: Returns all customer's cards based on given customer ID
      operationId: getCardsByCustomerId
      parameters:
        - name: id
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch, or empty collection of cards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'       
  /api/v1/customers/{id}/addresses:
    get:
      tags:
        - customer
      summary: Returns all customer's addresses
      description: Returns all customer's addresses based on given customer ID
      operationId: getAddressesByCustomerId
      parameters:
        - name: id
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch, or empty collection of addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'  
  /api/v1/addresses:
    get:
      tags:
        - address
      summary: Returns all user's addresses
      description: Returns all user's addresses, else empty collection
      operationId: getAllAddresses
      responses:
        '200':
          description: For successful fetch, or empty collection of addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'  
    post:
      tags:
        - address
      summary: Creates a new user address
      description: Creates and adds a new user address. Does nothing if address already exists.
      operationId: createAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAddressReq'
          application/xml:
            schema:
              $ref: '#/components/schemas/AddAddressReq'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Address' 
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /api/v1/addresses/{id}:
    get:
      tags:
        - address
      summary: Returns user's address
      description: Returns user's address based on given address ID.
      operationId: getAddressesById
      parameters:
        - name: id
          in: path
          description: Address Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Address'        
        '404':
          description: Address not found by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    delete:
      tags:
        - address
      summary: Deletes user's address
      description: Deletes user's address based on given address ID.
      operationId: deleteAddressesById
      parameters:
        - name: id
          in: path
          description: Address Identifier
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepts the deletion request and perform deletion. If ID does not exist, does nothing.
          content: {}      
  /api/v1/cards:
    get:
      tags:
        - card
      summary: Returns all user's cards
      description: Returns all user's cards, else empty collection
      operationId: getAllCards
      responses:
        '200':
          description: For successful fetch, or empty collection of addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'  
    post:
      tags:
        - card
      summary: Creates a new card
      description: Creates and adds a new card or replaces an existing one
      operationId: registerCard
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCardReq'
          application/xml:
            schema:
              $ref: '#/components/schemas/AddCardReq'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Card' 
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /api/v1/cards/{id}:
    get:
      tags:
        - card
      summary: Returns user's card
      description: Returns user's card based on given card ID.
      operationId: getCardById
      parameters:
        - name: id
          in: path
          description: card Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Card'        
        '404':
          description: Address not found by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    delete:
      tags:
        - card
      summary: Deletes card's address
      description: Deletes card's address based on given card ID.
      operationId: deleteCardById
      parameters:
        - name: id
          in: path
          description: Address Identifier
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepts the deletion request and perform deletion. If ID does not exist, does nothing.
          content: {}    
  /api/v1/payments:
    post:
      tags:
        - payment
      summary: Authorize a payment request
      description: Authorize a payment request.
      operationId: authorize
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReq'
          application/xml:
            schema:
              $ref: '#/components/schemas/PaymentReq'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Authorization' 
        '400':
          description: Invalid input
        '422':
          description: Validation exception
    get:
      tags:
        - payment
      summary: Returns the payment authorization
      description: Returns the payment authorization for the specified order
      operationId: getOrdersPaymentAuthorization
      parameters:
        - name: id
          in: query
          description: Order Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch, or empty collection of payments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Authorization'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Authorization'  
  /api/v1/shipping:
    post:
      tags:
        - shipping
      summary: Ship based on the specified shipping request
      description: Ship based on the specified shipping request
      operationId: shipOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingReq'
          application/xml:
            schema:
              $ref: '#/components/schemas/ShippingReq'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Authorization' 
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    get:
      tags:
        - shipping
      summary: Returns the Shipment
      description: Returns the Shipment for the specified order
      operationId: getShipmentByOrderId
      parameters:
        - name: id
          in: query
          description: Order Identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch, or empty collection of payments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'  
  /api/v1/products:
    put:
      tags:
        - product
      summary: Update an existing product
      description: Update an existing product by Id
      operationId: updateProduct
      requestBody:
        description: Update an existing product in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product' 
          application/xml:
            schema:
              $ref: '#/components/schemas/Product' 
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Product' 
        required: true
      responses:
        '200':
          description: For successful fetch, or empty collection of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'  
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
    post:
      tags:
        - product
      summary: Add a new product to the store
      description: Add a new product to the store
      operationId: addProduct
      requestBody:
        description: Create a new product in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product' 
          application/xml:
            schema:
              $ref: '#/components/schemas/Product' 
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Product' 
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Product'  
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
    get:
      tags:
        - product
      summary: Returns all the matched products
      description: Returns the products that matches the given query criteria
      operationId: queryProducts
      parameters:
        - name: tag
          in: query
          description: Product tag
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: Product name
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Query page number
          required: false
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          description: Query page size
          required: false
          schema:
            type: integer
            format: int32
            default: 10
      responses:
        '200':
          description: For successful fetch.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product' 
  /api/v1/products/{id}:
    get:
      tags:
        - product
      summary: Returns a product by id
      description: Returns a single product that matches the given product ID.
      operationId: getProductById
      parameters:
        - name: id
          in: path
          description: ID of product to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: For successful fetch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Product' 
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: Product not found by Id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
    put:
      tags:
        - product
      summary: Update a product in the store with form data
      description: Update a product in the store
      operationId: updateProductWithForm
      parameters:
        - name: id
          in: path
          description: ID of product that needs to be updated
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Status of the product that needs to be updated
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: name of the product that needs to be updated
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Product'  
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
    delete:
      tags:
        - product
      summary: Deletes a product
      description: Deletes a product in a store
      operationId: deleteProduct
      parameters:
        - name: api_key
          in: header
          description: ''
          required: false
          schema:
            type: string
        - name: id
          in: path
          description: Product with id to delete
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepts the deletion request and perform deletion. If ID does not exist, does nothing.
          content: {} 
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products 
  /api/v1/products/findByStatus:
    get:
      tags:
        - product
      summary: Find products by status
      description: Multiple status values can be provided with comma separated strings
      operationId: getProductsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: AVAILABLE
            enum:
              - AVAILABLE
              - PENIDNG
              - SOLD
      responses:
        '200':
          description: For successful fetch or empty collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Product' 
        '400':
          description: Invalid status value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
  /api/v1/products/findByTags:
    get:
      tags:
        - product
      summary: Find products by tags
      description: Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
      operationId: findProductsByTags
      parameters:
        - name: tags
          in: query
          description: Tags to filter by
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: For successful fetch or empty collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Product' 
        '400':
          description: Invalid tag value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
      security:
        - api_key: []
        - store_auth:
            - write:products
            - read:products
  /api/v1/products/{id}/uploadImage:
    post:
      tags:
        - product
      summary: uploads an image
      description: ''
      operationId: uploadFile
      parameters:
        - name: id
          in: path
          description: ID of the product to update
          required: true
          schema:
            type: string
        - name: additionalMetadata
          in: query
          description: Additional Metadata
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: For successful fetch, or empty collection of payments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppResponse' 
  /api/v1/store/inventory:
    get:
      tags:
        - store
      summary: Returns product inventories by status
      description: Returns a map of status codes to quantities
      operationId: getInventory
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                  format: int32
      security:
        - api_key: []
  /api/v1/store/order:
    post:
      tags:
        - store
      summary: Place an order for a pet
      description: Place a new order in the store
      operationId: placeOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
          application/xml:
            schema:
              $ref: '#/components/schemas/Order'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
  /api/v1/store/order/{orderId}:
    get:
      tags:
        - store
      summary: Find purchase order by ID
      description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          description: ID of order that needs to be fetched
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'          
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
    delete:
      tags:
        - store
      summary: Delete purchase order by ID
      description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
      operationId: deleteOrder
      parameters:
        - name: orderId
          in: path
          description: ID of the order that needs to be deleted
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '400':
          description: Invalid ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
  /api/v1/user:
    post:
      tags:
        - user
      summary: Create user
      description: This can only be done by the logged in user.
      operationId: createUser
      requestBody:
        description: Created user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
  /api/v1/user/batch:
    post:
      tags:
        - user
      summary: Creates list of users with given input array
      description: Creates list of users with given input array, maximum list size 500
      operationId: createUsersWithList
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'          
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: successful operation
  /api/v1/user/login:
    get:
      tags:
        - user
      summary: Logs user into the system
      description: ''
      operationId: loginUser
      parameters:
        - name: username
          in: query
          description: The user name for login
          required: false
          schema:
            type: string
        - name: password
          in: query
          description: The password for login in clear text
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              description: date in UTC when token expires
              schema:
                type: string
                format: date-time
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: string
        '400':
          description: Invalid username/password supplied
  /api/v1/user/logout:
    get:
      tags:
        - user
      summary: Logs out current logged in user session
      description: ''
      operationId: logoutUser
      parameters: []
      responses:
        default:
          description: successful operation
  /api/v1/user/{username}:
    get:
      tags:
        - user
      summary: Get user by user name
      description: ''
      operationId: getUserByName
      parameters:
        - name: username
          in: path
          description: 'The name that needs to be fetched. Use user1 for testing. '
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'          
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
    put:
      tags:
        - user
      summary: Update user by username
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: name that need to be deleted
          required: true
          schema:
            type: string
      requestBody:
        description: Update an existent user in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'          
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request, Invalid username supplied
        '409':
          description: User with given username already exist
        '422':
          description: Validation exception
    delete:
      tags:
        - user
      summary: Delete user by username
      description: This can only be done by the logged in user.
      operationId: deleteUser
      parameters:
        - name: username
          in: path
          description: The name that needs to be deleted
          required: true
          schema:
            type: string
      responses:
        '400':
          description: Invalid username supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppResponse'          
            application/xml:
              schema:
                $ref: '#/components/schemas/AppResponse'
          
components:
  schemas:
    Cart:
      description: Shopping cart of the user
      type: object
      properties:
        customerId:
          description: Id of the customer who possesses the cart
          type: string
        items:
          description: Collection of items in cart.
          type: array
          items:
            $ref: '#/components/schemas/Item'
    Item:
      description: Items in Shopping Cart of the user
      type: object
      properties:
        id:
          description: Item identifier
          type: string
        quantity:
          description: The item quantity
          type: integer
          format: int32
        unitPrice:
          description: The item's price per unit
          type: number
          format: double
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1000000
        username:
          type: string
          example: ferran
        address:
          type: array
          xml:
            name: addresses
            wrapped: true
          items:
            $ref: '#/components/schemas/Address'
      xml:
        name: customer
    Order:
      description: Represents an Order
      type: object
      properties:
        id:
          description: Order identifier
          type: string
        customer:
          $ref: '#/components/schemas/User'
        address: 
          $ref: '#/components/schemas/Address'
        card:
          $ref: '#/components/schemas/Card'
        date: 
          description: Order's date and time details
          type: string
          format: date-time
        items:
          description: Collection of order items.
          type: array
          items:
            $ref: '#/components/schemas/Item'
        total:
          description: Order total
          type: number
          format: double
        payment:
          $ref: '#/components/schemas/Payment'
        shipment:
          $ref: '#/components/schemas/Shipment'
        status:
          description: Order Status
          type: string
          example: APPROVED
          enum:
            - CREATED
            - PAID
            - SHIPPED
            - PAYMENT_FAILED
            - SHIPMENT_FAILED
            - COMPLETED
      xml:
        name: order
    AddAddressReq:
      allOf: 
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            userId: 
              type: string
   
      xml:
        name: AddAddressReq
    Address:
      type: object
      properties:
        number: 
          description: house, flat or apartment number
          type: string
        residency: 
          description: Society or Building name
          type: string
        street:
          description: street name
          type: string
          example: 437 Lytton
        city:
          description: city name
          type: string
          example: Ikeja
        state:
          description: state name
          type: string
          example: Lagos
        country:
          description: country name
          type: string
          example: Nigeria
        zip:
          type: string
          example: '94301'
      xml:
        name: Address
    Card:
      type: object
      properties:
        cardNumber:
          description: Card Number
          type: string
        expires:
          description: Expiration date
          type: string
        cvv:
          description: CVV code
          type: string
      xml:
        name: Card
    AddCardReq:
      description: Request object for new card registration.
      allOf:
        - $ref: '#/components/schemas/Card'
        - type: object
          properties:
            userId:
              type: object
      xml:
        name: AddCardReq
    Payment:
      description: Represents payment 
      type: object
      properties:
        authorized: 
          description: Flag that specified whether payment is authorized or not
          type: boolean
        message:
          description: Approval or Rejection message
          type: string
      xml:
        name: Payment
    Shipment:
      type: object
      properties:
        orderId:
          description: Order Identifier
          type: string
        carrier:
          description: Shipping Carrier
          type: string
          example: DHL
        trackingNumber:
          description: Shipping Tracking Number
          type: string
        estimatedDeliveryDate:
          description: Estimated delivery date
          type: string
          format: date
      xml:
        name: Shipment
    ShippingReq:
      description: Contains information required for Shipping request
      type: object
      properties:
        orderId:
          description: Order Identifier
          type: string
        address:
          $ref: '#/components/schemas/Address'
        itemCount:
          description: The number of items in the order
          type: integer
          format: int32
      xml:
        name: ShippingReq
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: men's shoes
      xml:
        name: category
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: john@email.com
        password:
          type: string
          example: '62635536'
        phone:
          type: string
          example: '123-123-3445'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: User
    Store:
      description: Contains details about user's store
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name: 
          type: string
        caption:
          type: string
        userId:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        inventory:
          $ref: '#/components/schemas/Item'
        orders:
          $ref: '#/components/schemas/Order'
      xml:
        name: Store
    NewOrder:
      description: Contains the new order request information
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/URI'
        address:
          $ref: '#/components/schemas/URI'
        card:
          $ref: '#/components/schemas/URI'
        items:
          $ref: '#/components/schemas/URI'
      xml:
        name: NewOrder
    URI:
      type: object
      xml:
        name: URI
    Authorization:
      type: object
      properties:
        orderId: 
          description: Order Identification
          type: string
        time:
          description: Timestamp when this authorization was created
          type: string
          format: date-time
        authorized:
          description: Flag that specify whether the payment is authorized
          type: boolean
        message:
          description: Approval or rejection message
          type: string
        error:
          description: Processing error description, if any
          type: string
      xml:
        name: Authorization
    PaymentReq:
      description: Contains the payment request information
      type: object
      properties: 
        orderId:
          description: Order Identifier
          type: string
        customer:
          $ref: '#/components/schemas/CustomerInfoOnCard'
        address:
          $ref: '#/components/schemas/Address'
        card: 
          $ref: '#/components/schemas/Card'
        amount:
          description: Payment amount
          type: number
          format: double
      xml:
        name: PaymentReq
    CustomerInfoOnCard:
      description: Customer information required for payment processing
      type: object
      properties:
        firstName:
          description: Customer first name
          type: string
        lastName:
          description: Customer last name
          type: string
      xml:
        name: CustomerInfoOnCard  
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name: 
          type: string
      xml:
        name: tag
    Product:
      required:
        - name
        - photoUrls
      description: Product information
      type: object
      properties:
        id:
          description: Product identifier
          type: string
        name:
          description: Product name
          type: string
        description:
          description: Product's description
          type: string
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          description: Product image's URL
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        price:
          description: Product price
          type: number
          format: double
        count:
          description: Product count
          type: integer
          format: int32
        tags:
          description: Tag associated with the product
          type: array
          xml:
            wrapped: true
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: product status in the store
          enum:
            - AVAILABLE
            - PENDING
            - SOLD
      xml:
        name: product
    ApiResponse:
      type: object
      properties:
        path:
          description: REST endpoint URI of the Request
          type: string
        message:
          description: short description (of the error)
          type: string
        method:
          description: Request method type 'GET, POST, PUT, DELETE' etc.
          example: 'GET'
          type: string
        status:
          description: HttpStatus of the (error) response
          type: string
        code:
          description: Unique application (error) code
          type: string
        traceId:
          description: unique id used to track error in a log
          type: string
        timestamp:
          description: date and time the error occured
          type: string
          format: date-time
        debugMessage:
          description: detail error message (of the error) to aid debugging
          type: string
        statusCode:
          description: status code of the error response
          type: string
        errorDetails:
          description: a breakdown of the error
          type: array
          items:
            $ref: '#/components/schemas/ApiSubError'
      xml:
        name: '##default'   
        
    ApiSubError:         
      type: object
      properties:
        object:
          description: object the caused the error
          type: string
        code:
          description: unique code of the error
          type: string
        error:
          description: error message 
          type: string
    AppResponse:
      type: object
      properties:
        success: 
          description: Flag indicating whether the request succeeded or failed
          type: boolean
        message: 
          description: simple message about the outcome of the request
          type: string  
        metadata: 
          $ref: '#/components/schemas/AppResponseMetadata'
        response: 
          $ref: '#/components/schemas/ApiResponse'
    AppResponseMetadata:
      type: object
      properties: 
        apiVersion:
          description: Current version of the Api
          type: string
          example: 1.1.0
        sendReportUri:
          description: URL to with a form to send error report
          type: string
        moreInfoUrl:
          description: URL link to frequently asked questions
          type: string
        technical:
          description: Email address of the technical team
          type: string
          
  requestBodies:
    ItemReq:
      description: Item object that needs to be added to the store as a new inventory
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Item'
        application/xml:
          schema:
            $ref: '#/components/schemas/Item'
    UserArray:
      description: List of user object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'
              
  securitySchemes:
    store_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://ecommerce.swagger.io/oauth/authorize
          scopes:
            write:itemd: modify products in a store
            read:items: read products
    api_key:
      type: apiKey
      name: api_key
      in: header