example.yml

openapi: 3.0.3
info:
  title: EazyShop Products APIs Definition
  description: |
      # About Us
      **EazyShop** is a open market product selling company. Any website can list our products by  using our _APIs_. Shipping & other logistics will be taken care by us. You will get an `Affiliate commision` for selling our products.
      # Categories suported
        - Mobiles
          - Apple
          - Samsung
          - OnePlus
        - Laptops
        - Televisions
        - Headphones
  termsOfService: https://eazyshop.com/terms/
  x-custom-info:
    comment: Some comments
    developers:
      - name: John Doe
        email: john@doe.com
      - name: Jane Doe
        email: jane@doe.com
  contact:
    name: API Support
    url: https://www.eazyshop.com/support
    email: support@eazyshop.com
  license:
    name: EazyShop License
    url: https://www.eazyshop.com/licenses/LICENSE-2.0.html
  version: 0.0.1
externalDocs:
  description: External Documentation
  url: https://example.com
servers:
  - url: https://development.eazyshop-server.com/v1
    description: Development server
tags:
  - name: Categories
    description: Categories-related operations
  - name: Products
    description: Products-related operations
  - name: Orders
    description: Orders-related operations
security:
  - BasicAuth: []
  - BearerAuth: []
  - ApiKeyAuth: []
  - oAuth2AuthCode:
    - read
    - write
    - admin
paths:
  /categories:
    get:
      tags:
        - Categories
      summary: List all catgories
      description: Returns the list of categories supported by EazyShop
      operationId: getCategories
      security:
        - BasicAuth: []
      parameters:
        - name: categoryId
          in: query
          schema:
            type: integer
            minimum: 100
            maximum: 1000
          examples:
            mobiles:
              summary: Use this example for mobiles
              value: 101
            laptops:
              value: 102
            headphones:
              value: 103
            televisions:
              value: 104
      responses:
        '200':
          description: A list of catgories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Category"
              examples:
                all-categories-data:
                  summary: Categories example data
                  value:
                    - categoryId: 101
                      name: Mobiles
                    - categoryId: 102
                      name: Laptops
                    - categoryId: 103
                      name: Headphones
                    - categoryId: 104
                      name: Televisions
                single-category-data:
                  summary: Single category example data
                  value:
                    - categoryId: 101
                      name: Mobiles
        '500':
          $ref: "#/components/responses/InternalServerError"
  /categories/{categoryId}:
    get:
      tags:
        - Categories
      summary: Return category details
      description: Returns the category details from EazyShop
      operationId: getCategoryDetails
      security: []
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
            minimum: 100
            maximum: 1000
          example: 102
      responses:
        '200':
          description: Return category details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        '500':
          $ref: "#/components/responses/InternalServerError"
  /products:
    get:
      tags:
        - Products
      summary: List all products
      description: |
        Returns the list of products supported by EazyShop
      operationId: getProducts
      parameters:
        - name: categoryId
          in: query
          schema:
            type: integer
            minimum: 100
            maximum: 1000
          example: 101
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
              examples:
                products-data:
                  summary: Products example data
                  value:
                    - productId: 101
                      name: Apple IPhone 13 Pro
                      price: 999.99
                      categoryName: Mobiles
                      quantity: 96
                    - productId: 102
                      name: Samsung S22 Ultra
                      price: 899.99
                      categoryName: Mobiles
                      quantity: 121
                    - productId: 103
                      name: OnePlus 10 Pro 5G
                      price: 750.99
                      categoryName: Mobiles
                      quantity: 67
        '500':
          $ref: "#/components/responses/InternalServerError"
  /products/{productId}:
    get:
      tags:
        - Products
      summary: Return product details
      description: |
        Returns the product details from  EazyShop
      operationId: getProductDetails
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
            minimum: 100
            maximum: 1000
          example: 101
      responses:
        '200':
          description: Return product details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        '500':
          $ref: "#/components/responses/InternalServerError"
  /orders:
    post:
      tags:
        - Orders
      summary: Create Order
      description: |
        Post order details to EazyShop for processing
        and shipping
      operationId: saveOrderDetails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  type: array
                  items:
                    $ref: "#/components/schemas/Product"
                address:
                  $ref: "#/components/schemas/Address"
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: integer
          links:
            GetOrderByOrderId:
              $ref: '#/components/links/GetOrderByOrderId'
        '500':
          $ref: "#/components/responses/InternalServerError"
    put:
      tags:
        - Orders
      summary: Update Order
      description: |
        Update order details to EazyShop for processing
        and shipping
      operationId: updateOrderDetails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: integer
                products:
                  type: array
                  items:
                    $ref: "#/components/schemas/Product"
                address:
                  $ref: "#/components/schemas/Address"
      responses:
        '200':
          description: Order details updated successfully
        '500':
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - Orders
      summary: Delete Order
      description: Delete order details from EazyShop
      operationId: deleteOrderDetails
      parameters:
        - $ref: "#/components/parameters/orderIdQueryParam"
      responses:
        '204':
          description: Order details cancelled successfully
        '500':
          $ref: "#/components/responses/InternalServerError"
    get:
      tags:
        - Orders
      summary: Get Order Details
      description: Get order details from EazyShop
      operationId: getOrderDetails
      parameters:
        - $ref: "#/components/parameters/orderIdQueryParam"
      responses:
        '200':
          description: Fetch Order details successfully
          content:
            application/json:
              schema: 
                type: object
                properties:
                  orderId:
                    type: integer
                  products:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
                  address:
                    $ref: "#/components/schemas/Address"
        '500':
          $ref: "#/components/responses/InternalServerError"
  /orders/{orderId}:
    get:
      tags:
        - Orders
      summary: Get Order Details
      description: Get order details from EazyShop
      operationId: getOrderDetailsUsingPathParam
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/orderIdPathParam"
      responses:
        '200':
          description: Fetch Order details successfully
          content:
            application/json:
              schema: 
                type: object
                properties:
                  orderId:
                    type: integer
                  products:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
                  address:
                    $ref: "#/components/schemas/Address"
        '500':
          $ref: "#/components/responses/InternalServerError"
  /oneOfOrder:
    post:
      tags:
      - Orders
      summary: Insert OneOf the Order Details
      description: Insert OneOf the Order Details into Eazyshop
      operationId: demoOfOneOf
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  type: object
                  oneOf:
                    - $ref: '#/components/schemas/Mobile'
                    - $ref: '#/components/schemas/Laptop'
                address:
                  $ref: '#/components/schemas/Address'
              required:
                - products
                - address
      responses:
        '200':
          description: Order placed successfully
  /anyOfOrder:
    get:
      tags:
      - Orders
      summary: Get Order Details
      description: Get Order Details based on Order ID
      operationId: demoOfAnyOf
      parameters:
        - $ref: "#/components/parameters/orderIdQueryParam"
        - name: fetchType
          in: query
          required: true
          schema:
            type: string
            enum:
              - summary
              - details
          description: >
            Fetch Type:
             * `summary` - Will provide Order Summary
             * `details` - Will provide Order Summary & Order Address
      responses:
        '200':
          description: Return product details
          content:
            application/json:
              schema:
               anyOf:
                - $ref: '#/components/schemas/OrderSummary'
                - $ref: '#/components/schemas/OrderAddress'      
components:
  parameters:
    orderIdQueryParam:
      name: orderId
      in: query
      required: true
      schema:
        type: integer
    orderIdPathParam:
      name: orderId
      in: path
      required: true
      schema:
        type: integer
  schemas:
    Address:
      type: object
      properties:
        addressLine:
          type: string
        city:
          type: string
        state:
          type: string
          enum:
            - California
            - Texas
            - Indiana
            - NewYork
        zipcode:
          type: string
        isOfficeAddress:
          type: boolean
      required: [addressLine, city, state, zipcode]
    Product:
      type: object
      properties:
        productId:
          type: integer
        name:
         type: string
        price:
          type: number
          format: float
        categoryName:
          type: string
          nullable: true
        releaseDate:
          type: string
          format: date
          readOnly: true
        quantity:
          type: integer
          description: |
            ***Quantity*** represents `stock` value when this field is being sent by EazyShop.Where as in the scenarios of consumer sending this feild, it represents `number of product items` inside the order. Consumers are expected to handle the scenario of stopping the end user <u>*when the stock value is 0*</u>
    Category:
      type: object
      properties:
        categoryId:
          type: integer
        name:
          type: string
    Mobile:
      allOf:
        - $ref: "#/components/schemas/Product"
        - type: object
          properties:
            networkType:
              type: string
              enum:
                - 4G
                - 5G
          required: [networkType]
    Laptop:
      allOf:
        - $ref: "#/components/schemas/Product"
        - type: object
          properties:
            ram:
              type: string
              enum:
                - 8 GB
                - 16 GB
                - 32 GB
          required: [ram]
    OrderSummary:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    OrderAddress:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
  responses:
    InternalServerError:
      description: |
        An error occured while processing the request.
        Please contact support@eazyshop.com
  links:
    GetOrderByOrderId:
      description: >
        The `orderId` value returned in the response can be used as input parameter in `GET /orders`.
      operationId: getProductDetails
      parameters:
        orderId: '$response.body#/orderId'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:        
      type: apiKey
      in: header
      name: X-API-KEY
    oAuth2AuthCode:
      type: oauth2
      flows: 
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/api/oauth.access
          scopes:
            read: Read only access
            write: Read Write access
            admin: Admin access