swagger.yaml

---
openapi: 3.0.3

info:
  version: '2.1.0'
  title: Products API Definition
  description: Presents a simple product API for educational and research purposes.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Bug Tracker
    url: https://github.com/sergeyklay/provider-pact-example/issues

servers:
  - description: Localhost
    url: http://127.0.0.1:5000

tags:
  - name: products
    description: Products related API.

components:
  headers:
    LastModifiedHeader:
      description: |-
        The `Last-Modified` HTTP response header contains a date and time when
        the origin server believes the resource was last modified.
      schema:
        type: string
        minLength: 29
        maxLength: 29
      example: Mon, 04 Feb 2016 23:04:04 GMT
    LocationHeader:
      description: |-
        The `Location` HTTP response header used in responses to refer to the
        primary resource created by the request.
      schema:
        type: string
      example: https://api.example.com/v1/products/1
    ETagHeader:
      description: The `ETag` HTTP response header is an identifier for a specific version of a resource.
      schema:
        type: string
        minLength: 2
        maxLength: 44
      example: '"92cfceb39d57d914ed8b14d0e37643de0797ae56"'
    X-Pagination:
      description: The `X-Pagination` HTTP response header contains the pagination information.
      schema:
        type: object
        required:
          - total
          - total_pages
        properties:
          total:
            description: The total number of items across all pages in the paginated collection.
            type: integer
            format: int32
            minimum: 0
          total_pages:
            description: The total number of pages in the paginated collection.
            type: integer
            format: int32
            minimum: 0
          page:
            description: The current page number.
            type: integer
            format: int32
            minimum: 1
          first_page:
            description: The number of the first page in the paginated collection.
            type: integer
            format: int32
            minimum: 1
          last_page:
            description: The number of the last page in the paginated collection.
            type: integer
            format: int32
            minimum: 1
          previous_page:
            description: |-
              The number of the previous page in the paginated collection.
              May not be present if the current page is the first page.
            type: integer
            format: int32
            minimum: 1
          next_page:
            description: |-
              The number of the next page in the paginated collection.
              May not be present if the current page is the last page.
            type: integer
            format: int32
            minimum: 1
      examples:
        multiple_products:
          value:
            total: 1021
            total_pages: 103
            first_page: 1
            last_page: 103
            page: 11
            previous_page: 1
            next_page: 3
  schemas:
    Product:
      title: Product
      type: object
      properties:
        id:
          type: integer
          format: int32
          minimum: 1
          example: 42
        name:
          type: string
          example: iPhone 9
          minLength: 1
          maxLength: 64
        description:
          type: string
          example: An Apple mobile which is nothing like apple
          maxLength: 512
        price:
          type: number
          minimum: 0
          example: 549
        discount:
          type: number
          minimum: 0.0
          example: 12.96
        rating:
          type: number
          minimum: 0.0
          maximum: 5.0
          example: 4.69
        stock:
          type: integer
          format: int32
          minimum: 0
          example: 856
        brand_id:
          type: integer
          format: int32
          minimum: 1
          example: 7
        category_id:
          type: integer
          format: int32
          minimum: 1
          example: 13
        created_at:
          description: Creation date and time in ISO 8601 full-time format
          type: string
          format: date-time
          minimum: 1
          example: '1994-11-05T08:15:30.1023Z'
        updated_at:
          description: Updating date and time in ISO 8601 full-time format
          type: string
          format: date-time
          minimum: 1
          example: '2002-01-31T23:00:00.1234Z'
      required:
        - id
        - name
        - price
        - discount
        - rating
        - stock
        - brand_id
        - category_id
        - created_at
        - updated_at
    BasicErrorModel:
      title: Basic Error Model
      type: object
      required:
        - code
        - status
      properties:
        code:
          title: The HTTP response code indicating an error.
          type: integer
          format: int32
        status:
          title: A textual description of the error status that supplements the HTTP response code.
          type: string
    NotFoundErrorModel:
      title: Not Found Error Model
      description: |-
        The 404 (Not Found) status code means that the requested resource was
        not found on the server and cannot be returned in response to the request.
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          properties:
            code:
              example: 404
            status:
              example: Not Found
            message:
              title: A message indicating the reason for the error.
              type: string
              example: Product not found
    PreconditionFailedErrorModel:
      title: Precondition Failed Error Model
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          properties:
            code:
              example: 412
            status:
              example: Precondition Failed
    UnprocessableEntityErrorModel:
      title: Unprocessable Entity Error Model
      description: |-
        The 422 status code means the server understands the content
        type of the request entity, and the syntax of the request entity
        is correct but was unable to process the contained instructions.
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          properties:
            code:
              example: 422
            errors:
              title: Validation errors in parameters or request body.
              type: object
              example:
                json:
                  brand_id:
                    - Missing data for required field.
                  rating:
                    - Must be greater than or equal to 0.0 and less than or equal to 5.0.
            message:
              title: A message indicating the reason for the error.
              type: string
              example: Product with this name already exists
            status:
              example: Unprocessable Entity
    PreconditionRequiredErrorModel:
      title: Precondition Required Error Model
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          properties:
            code:
              example: 428
            status:
              example: Precondition Required
  parameters:
    ProductIdParameter:
      in: path
      name: id
      description: Product ID param
      schema:
        type: integer
        format: int32
        minimum: 1
      required: true
      examples:
        success:
          summary: An ID of an existing product
          value: 42
        not-found:
          summary: An ID of an not existing product
          value: 10000000

paths:
  /v2/products:
    get:
      summary: Get list of products
      description: Returns a list of all products.
      operationId: v2.products.list
      tags: [products]
      parameters:
        - in: query
          name: cid
          description: Filter by product category.
          required: false
          schema:
            type: string
          examples:
            category_12:
              value: 12
              summary: Products from Category ID 12
            category_13:
              value: 13
              summary: Products from Category ID 13
        - in: query
          name: bid
          description: Filter by product brand.
          required: false
          schema:
            type: string
          examples:
            brand_7:
              value: 7
              summary: Products for Brand ID 7
            brand_9:
              value: 9
              summary: Products for Brand ID 9
        - in: query
          name: q
          description: Search term.
          required: false
          schema:
            type: string
          examples:
            term:
              value: Samsung
              summary: A sample search keyword
      responses:
        '200':
          description: List of products
          headers:
            ETag:
              $ref: '#/components/headers/ETagHeader'
            X-Pagination:
              $ref: '#/components/headers/X-Pagination'
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
              examples:
                products_list:
                  value:
                    - id: 1
                      name: iPhone 9
                      description: An Apple mobile which is nothing like apple
                      price: 549
                      discount: 12.96
                      rating: 4.69
                      stock: 94
                      brand_id: 7
                      category_id: 13
                      created_at: '1994-11-05T08:15:30.2345Z'
                      updated_at: '2002-01-31T23:00:00.1234Z'
                    - id: 6
                      name: Samsung Galaxy Book
                      description: Samsung Galaxy Book S (2020) Laptop With Intel Lakefield Chip, 8GB of RAM Launched
                      price: 1499
                      discount: 4.15
                      rating: 4.25
                      stock: 50
                      brand_id: 8
                      category_id: 13
                      created_at: '2010-05-01T01:14:31.876Z'
                      updated_at: '2016-12-15T20:16:01.987Z'
                  summary: A response products list
                empty_list:
                  value: []
                  summary: En empty response

    post:
      summary: Create product
      description: Create a new product in the database.
      operationId: v2.products.create
      tags: [products]
      requestBody:
        required: true
        content:
          application/json; charset=utf-8:
            schema:
              type: object
              required:
                - name
                - price
                - discount
                - rating
                - stock
                - brand_id
                - category_id
              properties:
                name:
                  type: string
                  example: iPhone 9
                  minLength: 1
                  maxLength: 64
                description:
                  type: string
                  example: An Apple mobile which is nothing like apple
                  maxLength: 512
                price:
                  type: number
                  minimum: 0
                  example: 549
                discount:
                  type: number
                  minimum: 0.0
                  example: 12.96
                rating:
                  type: number
                  minimum: 0.0
                  maximum: 5.0
                  example: 4.69
                stock:
                  type: integer
                  format: int32
                  minimum: 0
                  example: 856
                brand_id:
                  type: integer
                  format: int32
                  minimum: 1
                  example: 7
                category_id:
                  type: integer
                  format: int32
                  minimum: 1
                  example: 13
      responses:
        '200':
          description: A product
          headers:
            Location:
              $ref: '#/components/headers/LocationHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                iPhone:
                  value:
                    id: 1
                    name: iPhone 9
                    description: An Apple mobile which is nothing like apple
                    price: 549
                    discount: 12.96
                    rating: 4.69
                    stock: 94
                    brand_id: 7
                    category_id: 11
                    created_at: '1994-11-05T08:15:30.2345Z'
                    updated_at: '2002-01-31T23:00:00.1234Z'
                Samsung:
                  value:
                    id: 6
                    name: Samsung Galaxy Book
                    description: Samsung Galaxy Book S (2020) Laptop With Intel Lakefield Chip, 8GB of RAM Launched
                    price: 1499
                    discount: 4.15
                    rating: 4.25
                    stock: 50
                    brand_id: 9
                    category_id: 12
                    created_at: '2010-05-01T01:14:31.876Z'
                    updated_at: '2016-12-15T20:16:01.987Z'
        '422':
          description: Unprocessable Entity
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityErrorModel'

  '/v2/products/{id}':
    get:
      summary: Get single product
      description: Returns a single product.
      operationId: v2.products.read
      tags: [products]
      parameters:
        - $ref: '#/components/parameters/ProductIdParameter'
      responses:
        '200':
          description: A product
          headers:
            Last-Modified:
              $ref: '#/components/headers/LastModifiedHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                iPhone:
                  value:
                    id: 1
                    name: iPhone 9
                    description: An Apple mobile which is nothing like apple
                    price: 549
                    discount: 12.96
                    rating: 4.69
                    stock: 94
                    brand_id: 7
                    category_id: 11
                    created_at: '1994-11-05T08:15:30.2345Z'
                    updated_at: '2002-01-31T23:00:00.1234Z'
                Samsung:
                  value:
                    id: 6
                    name: Samsung Galaxy Book
                    description: Samsung Galaxy Book S (2020) Laptop With Intel Lakefield Chip, 8GB of RAM Launched
                    price: 1499
                    discount: 4.15
                    rating: 4.25
                    stock: 50
                    brand_id: 9
                    category_id: 12
                    created_at: '2010-05-01T01:14:31.876Z'
                    updated_at: '2016-12-15T20:16:01.987Z'
        '404':
          description: Product not found
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/NotFoundErrorModel'

    # This request is required to be conditional
    delete:
      summary: Delete product
      description: Deletes a specific product and returns status code 204 if successful, otherwise - 404.
      operationId: v2.products.delete
      tags: [ products ]
      parameters:
        - $ref: '#/components/parameters/ProductIdParameter'
        - in: header
          name: If-Match
          description: An identifier for a specific version of a resource.
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 44
          examples:
            simple:
              value: '"92cfceb39d57d914ed8b14d0e37643de0797ae56"'
              summary: Example of typical ETag header
      responses:
        '204':
          description: Successful operation
        '404':
          description: Product not found
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/NotFoundErrorModel'
        '412':
          description: Precondition Failed
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PreconditionFailedErrorModel'
        '428':
          description: Precondition Required
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PreconditionRequiredErrorModel'