---
openapi: 3.1.1
info:
  title: Ordering Service API
  description:
    Orchestrates the entire order lifecycle, from creation to completion
    or cancellation, for the BookWorm platform
  contact:
    name: Nhan Nguyen
    url: https://github.com/foxminchan
    email: nguyenxuannhan407@gmail.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: "1.0"
externalDocs:
  description: Documentation
  url: https://github.com/foxminchan/BookWorm
servers:
  - url: "{protocol}://{environment}.ordering.bookworm.com"
    description: Before deploying to production, ensure the environment is set correctly
    variables:
      protocol:
        enum:
          - https
          - http
        default: https
      environment:
        enum:
          - dev
          - stg
          - qa
        default: dev
  - url: "{protocol}://ordering.bookworm.com"
    description: Production
    variables:
      protocol:
        enum:
          - https
        default: https
security:
  - OAuth:
      - ordering
paths:
  "/api/v1/orders/{id}/summary":
    get:
      tags:
        - Order
      summary: Get Order Summary
      description: Get an order summary if it exists
      x-eventcatalog-message-type: query
      operationId: SummaryOrderEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: id
          in: path
          description: The unique identifier of the order to be retrieved
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the order to be retrieved
            example: "019622cf-6bd5-7499-bc18-31f71acbad44"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OrderSummaryInfo"
              example:
                id: "019622cf-6bd5-7499-bc18-31f71acbad44"
                status: "New"
                totalPrice: 100.00
        "401":
          description: Unauthorized - Access token is missing or invalid.
  "/api/v1/orders":
    get:
      tags:
        - Order
      summary: List Orders
      description: List orders with pagination and filtering
      x-eventcatalog-message-type: query
      operationId: ListOrdersEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: PageIndex
          in: query
          description: Number of items to return in a single page of results
          schema:
            type: integer
            format: int32
            default: 1
            description: The page index to return
            minimum: 1
            example: 1
        - name: PageSize
          in: query
          description: Number of items to return in a single page of results
          schema:
            type: integer
            format: int32
            default: 20
            description: The page size to return
            minimum: 1
            example: 20
        - name: Status
          in: query
          description: Status to filter results by
          schema:
            "$ref": "#/components/schemas/NullableOfStatus"
        - name: BuyerId
          in: query
          description: Buyer ID to filter results by
          schema:
            type:
              - string
              - "null"
            format: uuid
            default: null
            description: The unique identifier of the buyer to be retrieved
            example: "019622a3-a3ae-7705-a11b-a08f2a2ca621"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PagedResultOfOrderDto"
              examples:
                orders-empty:
                  summary: No orders found
                  value:
                    items: []
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 0
                    totalPages: 0
                    hasPreviousPage: false
                    hasNextPage: false
                orders-single:
                  summary: Single order
                  value:
                    items:
                      - id: "019622cf-6bd5-7499-bc18-31f71acbad44"
                        date: "2021-01-01T00:00:00Z"
                        status: "New"
                        total: 100.00
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 1
                    totalPages: 1
                    hasPreviousPage: false
                    hasNextPage: false
                orders-multiple:
                  summary: Multiple orders
                  value:
                    items:
                      - id: "019622cf-6bd5-7499-bc18-31f71acbad44"
                        date: "2021-01-01T00:00:00Z"
                        status: "New"
                        total: 100.00
                      - id: "019622d1-3613-737e-8d58-af7db6317153"
                        date: "2021-01-02T00:00:00Z"
                        status: "Completed"
                        total: 200.00
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 2
                    totalPages: 1
                    hasPreviousPage: false
                    hasNextPage: false
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/HttpValidationProblemDetails"
              examples:
                invalid-page-index:
                  summary: Invalid page index
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "PageIndex"
                        errorMessage: "'PageIndex' must be greater than 0."
                        severity: 0
                invalid-page-size:
                  summary: Invalid page size
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "PageSize"
                        errorMessage: "'PageSize' must be greater than 0."
                        severity: 0
        "401":
          description: Unauthorized - Access token is missing or invalid.
    post:
      tags:
        - Order
      summary: Create Order
      description: Create a new order
      x-eventcatalog-message-type: command
      operationId: CreateOrderEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: X-Request-Id
          in: header
          description: The idempotency key of the order to be created
          required: true
          schema:
            type: string
            description: The idempotency key of the order to be created
            example: "019622d1-014e-7bb7-b279-42a43ab74347"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: string
                format: uuid
                description: The unique identifier of the order to be created
                example: "019622d1-3613-737e-8d58-af7db6317153"
        "401":
          description: Unauthorized - Access token is missing or invalid.
  "/api/v1/orders/{id}":
    get:
      tags:
        - Order
      summary: Get Order
      description: Get an order if it exists
      x-eventcatalog-message-type: query
      operationId: GetOrderEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: id
          in: path
          description: The unique identifier of the order to be retrieved
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the order to be retrieved
            example: "019622d1-89ba-791c-a11c-f1821326441b"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OrderDetailDto"
              example:
                id: "019622d1-89ba-791c-a11c-f1821326441b"
                date: "2021-01-01T00:00:00Z"
                status: "New"
                total: 100.00
                items:
                  - id: "019622a3-a3ae-7705-a11b-a08f2a2ca621"
                    name: "AI Engineering"
                    quantity: 1
                    price: 100.00
                  - id: "029622a4-a3ae-7705-a11b-a08f2a2ca622"
                    name: "Software Architecture: The Hard Parts"
                    quantity: 1
                    price: 56.00
                  - id: "039622a5-a3ae-7705-a11b-a08f2a2ca623"
                    name: "The Pragmatic Programmer: From Journeyman to Master"
                    quantity: 1
                    price: 45.00
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              examples:
                order-not-found:
                  summary: Order not found
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Not Found"
                    status: 404
                    detail: "Order with id 019622d1-89ba-791c-a11c-f1821326441b not found."
    delete:
      tags:
        - Order
      summary: Delete Order
      description: Delete an order if it exists
      operationId: DeleteOrderEndpoint
      parameters:
        - name: id
          in: path
          description: The unique identifier of the order to be deleted
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the order to be deleted
            example: "019622d1-c7df-7d66-82fe-8124d493cb1d"
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              examples:
                order-not-found:
                  summary: Order not found
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Not Found"
                    status: 404
                    detail: "Order with id 019622d1-c7df-7d66-82fe-8124d493cb1d not found."
  "/api/v1/orders/{orderId}/complete":
    patch:
      tags:
        - Order
      summary: Complete Order
      description: Complete an order
      x-eventcatalog-message-type: command
      operationId: CompleteOrderEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: X-Request-Id
          in: header
          description: The idempotency key of the order to be completed
          required: true
          schema:
            type: string
            description: The idempotency key of the order to be completed
            example: "019622d1-014e-7bb7-b279-42a43ab74347"
        - name: orderId
          in: path
          description: The unique identifier of the order to be completed
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the order to be completed
            example: "019622d1-89ba-791c-a11c-f1821326441b"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OrderDetailDto"
              examples:
                order-detail:
                  summary: Order detail
                  value:
                    id: "019622d1-89ba-791c-a11c-f1821326441b"
                    date: "2021-01-01T00:00:00Z"
                    status: "Completed"
                    total: 100.00
                    items:
                      - id: "019622a3-a3ae-7705-a11b-a08f2a2ca621"
                        name: "AI Engineering"
                        quantity: 1
                        price: 100.00
                      - id: "029622a4-a3ae-7705-a11b-a08f2a2ca622"
                        name: "Software Architecture: The Hard Parts"
                        quantity: 1
                        price: 56.00
                      - id: "039622a5-a3ae-7705-a11b-a08f2a2ca623"
                        name: "The Pragmatic Programmer: From Journeyman to Master"
                        quantity: 1
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              examples:
                order-not-found:
                  summary: Order not found
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Not Found"
                    status: 404
                    detail: "Order with id 019622d1-89ba-791c-a11c-f1821326441b not found."
  "/api/v1/orders/{orderId}/cancel":
    patch:
      tags:
        - Order
      summary: Cancel Order
      description: Cancel an order
      x-eventcatalog-message-type: command
      operationId: CancelOrderEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: X-Request-Id
          in: header
          description: The idempotency key of the order to be cancelled
          required: true
          schema:
            type: string
            description: The idempotency key of the order to be cancelled
            example: "019622d1-014e-7bb7-b279-42a43ab74347"
        - name: orderId
          in: path
          description: The unique identifier of the order to be cancelled
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the order to be cancelled
            example: "019622d1-89ba-791c-a11c-f1821326441b"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OrderDetailDto"
              examples:
                order-detail:
                  summary: Order detail
                  value:
                    id: "019622d1-89ba-791c-a11c-f1821326441b"
                    date: "2021-01-01T00:00:00Z"
                    status: "Cancelled"
                    total: 100.00
                    items:
                      - id: "019622a3-a3ae-7705-a11b-a08f2a2ca621"
                        name: "AI Engineering"
                        quantity: 1
                        price: 100.00
                      - id: "029622a4-a3ae-7705-a11b-a08f2a2ca622"
                        name: "Software Architecture: The Hard Parts"
                        quantity: 1
                        price: 56.00
                      - id: "039622a5-a3ae-7705-a11b-a08f2a2ca623"
                        name: "The Pragmatic Programmer: From Journeyman to Master"
                        quantity: 1
                        price: 45.00
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              examples:
                order-not-found:
                  summary: Order not found
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Not Found"
                    status: 404
                    detail: "Order with id 019622d1-89ba-791c-a11c-f1821326441b not found."
  "/api/v1/buyers/address":
    patch:
      tags:
        - Buyer
      summary: Update Buyer Address
      description: Update the current buyer's address
      x-eventcatalog-message-type: command
      operationId: UpdateAddressEndpoint
      security:
        - OAuth:
            - ordering
      requestBody:
        description: The command to update the current buyer's address
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateAddressCommand"
            example:
              street: "123 Main St"
              city: "Anytown"
              province: "CA"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BuyerDto"
              examples:
                buyer-detail:
                  summary: Buyer detail
                  value:
                    id: "019622d7-e45c-7ccb-868f-509b69559883"
                    name: "John Doe"
                    address: "123 Main St, Anytown, USA"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/HttpValidationProblemDetails"
              examples:
                empty-street:
                  summary: Empty street
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "Street"
                        errorMessage: "'Street' must not be empty."
                        severity: 0
                empty-city:
                  summary: Empty city
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "City"
                        errorMessage: "'City' must not be empty."
                        severity: 0
                empty-province:
                  summary: Empty province
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "Province"
                        errorMessage: "'Province' must not be empty."
                        severity: 0
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              example:
                type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                title: "Not Found"
                status: 404
                detail: "Buyer with id 019622d7-e45c-7ccb-868f-509b69559883 not found."
  "/api/v1/buyers":
    get:
      tags:
        - Buyer
      summary: List Buyers
      description: List all buyers with pagination options
      x-eventcatalog-message-type: query
      operationId: ListBuyersEndpoint
      security:
        - OAuth:
            - ordering
      parameters:
        - name: PageIndex
          in: query
          description: Number of items to return in a single page of results
          schema:
            type: integer
            format: int32
            default: 1
            description: The page index to return
            minimum: 1
            example: 1
        - name: PageSize
          in: query
          description: Number of items to return in a single page of results
          schema:
            type: integer
            format: int32
            default: 20
            description: The page size to return
            minimum: 1
            example: 20
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PagedResultOfBuyerDto"
              examples:
                buyers-empty:
                  summary: No buyers found
                  value:
                    items: []
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 0
                    totalPages: 0
                    hasPreviousPage: false
                    hasNextPage: false
                buyers-single:
                  summary: Single buyer
                  value:
                    items:
                      - id: "019622d7-e45c-7ccb-868f-509b69559883"
                        name: "John Doe"
                        address: "123 Main St, Anytown, USA"
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 1
                    totalPages: 1
                    hasPreviousPage: false
                    hasNextPage: false
                buyers-multiple:
                  summary: Multiple buyers
                  value:
                    items:
                      - id: "019622d7-e45c-7ccb-868f-509b69559883"
                        name: "John Doe"
                        address: "123 Main St, Anytown, USA"
                      - id: "029622d8-e45c-7ccb-868f-509b69559884"
                        name: "Jane Smith"
                        address: "456 Maple Ave, Anytown, USA"
                    pageIndex: 1
                    pageSize: 20
                    totalItems: 2
                    totalPages: 1
                    hasPreviousPage: false
                    hasNextPage: false
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "403":
          description: Forbidden - The permission requirements are not met.
    post:
      tags:
        - Buyer
      summary: Create Buyer
      description: Create a new buyer in the system
      x-eventcatalog-message-type: command
      operationId: CreateBuyerEndpoint
      security:
        - OAuth:
            - ordering
      requestBody:
        description: The command to create a new buyer
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateBuyerCommand"
            example:
              street: "123 Main St"
              city: "Anytown"
              province: "CA"
        required: true
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: string
                format: uuid
                description: The unique identifier of the buyer to be created
                example: "019622d6-d8ae-7512-9b28-3f5591426db8"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/HttpValidationProblemDetails"
              examples:
                empty-street:
                  summary: Empty street
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "Street"
                        errorMessage: "'Street' must not be empty."
                        severity: 0
                empty-city:
                  summary: Empty city
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "City"
                        errorMessage: "'City' must not be empty."
                        severity: 0
                empty-province:
                  summary: Empty province
                  value:
                    type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                    title: "Validation failed"
                    status: 400
                    detail: "One or more validation errors has occurred"
                    errors:
                      - propertyName: "Province"
                        errorMessage: "'Province' must not be empty."
                        severity: 0
  "/api/v1/buyers/me":
    get:
      tags:
        - Buyer
      summary: Get Buyer
      description: Get the current buyer's information
      operationId: GetBuyerEndpoint
      parameters:
        - name: Id
          in: query
          description: Only 'ADMIN' role can retrieve other users' data
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the buyer to be retrieved
            example: "019622d7-313a-777a-9077-4323b9f59fb9"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BuyerDto"
              examples:
                buyer-detail:
                  summary: Buyer detail
                  value:
                    id: "019622d7-e45c-7ccb-868f-509b69559883"
                    name: "John Doe"
                    address: "123 Main St, Anytown, USA"
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              example:
                type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                title: "Not Found"
                status: 404
                detail: "Buyer with id 019622d7-e45c-7ccb-868f-509b69559883 not found."
  "/api/v1/buyers/{id}":
    delete:
      tags:
        - Buyer
      summary: Delete Buyer
      description: Delete a buyer by ID if it exists
      operationId: DeleteBuyerEndpoint
      parameters:
        - name: id
          in: path
          description: The unique identifier of the buyer to be deleted
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the buyer to be deleted
            example: "019622d7-6ba8-7edc-9340-8c93524c3819"
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized - Access token is missing or invalid.
        "403":
          description: Forbidden - The permission requirements are not met.
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"
              example:
                type: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
                title: "Not Found"
                status: 404
                detail: "Buyer with id 019622d7-e45c-7ccb-868f-509b69559883 not found."
components:
  schemas:
    BuyerDto:
      type: object
      readOnly: true
      description: The buyer details
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the buyer
          example: "019622d7-e45c-7ccb-868f-509b69559883"
        name:
          type:
            - "string"
            - "null"
          description: The name of the buyer
          example: "John Doe"
        address:
          type:
            - "string"
            - "null"
          description: The address of the buyer
          example: "123 Main St, Anytown, USA"
    CreateBuyerCommand:
      required:
        - street
        - city
        - province
      type: object
      writeOnly: true
      description: The command to create a buyer
      properties:
        street:
          type: string
          description: The street of the buyer
          maxLength: 50
          example: "123 Main St"
        city:
          type: string
          description: The city of the buyer
          maxLength: 50
          example: "Anytown"
        province:
          type: string
          description: The province of the buyer
          maxLength: 50
          example: "CA"
    HttpValidationProblemDetails:
      type: object
      readOnly: true
      x-scalar-ignore: true
      description: RFC 9110 (https://tools.ietf.org/html/rfc9110#section-15.5.1)
      properties:
        type:
          type: string
          description: The type of the problem
          example: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
        title:
          type: string
          description: The title of the problem
          example: "Validation failed"
        status:
          type: integer
          format: int32
          description: The status code of the problem
          example: 400
        detail:
          type: string
          description: The detail of the problem
          example: "One or more validation errors has occurred"
        errors:
          type: array
          description: The validation errors
          example:
            - propertyName: "Street"
              errorMessage: "'Street' must not be empty."
              severity: 0
          items:
            type: object
            properties:
              propertyName:
                type: string
                description: The name of the property that failed validation
                example: "Street"
              errorMessage:
                type: string
                description: The error message describing the validation failure
                example: "'Street' must not be empty."
              attemptedValue:
                type: object
                description: The value that was attempted
                example: null
              customState:
                type: object
                description: Custom state information
                example: null
              severity:
                type: integer
                format: int32
                description: The severity level of the error
                example: 0
              errorCode:
                type:
                  - "string"
                  - "null"
                description: The error code
                example: null
              formattedMessagePlaceholderValues:
                type: object
                description: Placeholder values for the formatted message
                example: null
    NullableOfStatus:
      description: The status of the order
      readOnly: true
      enum:
        - New
        - Cancelled
        - Completed
        -
      default:
    OrderDetailDto:
      type: object
      readOnly: true
      description: The order details
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the order
          example: "019622e7-87ac-7bd1-aa9c-35803d8a1e50"
        date:
          type: string
          format: date-time
          description: The date of the order
          example: "2021-01-01T00:00:00Z"
        total:
          type: number
          format: double
          description: The total price of the order
          example: 100.00
        status:
          "$ref": "#/components/schemas/Status"
        items:
          type: array
          description: The items of the order
          items:
            "$ref": "#/components/schemas/OrderItemDto"
    OrderDto:
      type: object
      readOnly: true
      description: The order summary
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the order
          example: "019622e7-87ac-7bd1-aa9c-35803d8a1e50"
        date:
          type: string
          format: date-time
          description: The date of the order
          example: "2021-01-01T00:00:00Z"
        total:
          type: number
          format: double
          description: The total price of the order
          example: 100.00
        status:
          "$ref": "#/components/schemas/Status"
    OrderItemDto:
      type: object
      readOnly: true
      description: The order item details
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the order item
          example: "019622e7-87ac-7bd1-aa9c-35803d8a1e50"
        quantity:
          type: integer
          format: int32
          description: The quantity of the order item
          example: 1
        price:
          type: number
          format: double
          description: The price of the order item
          example: 100.00
        name:
          type: string
          description: The name of the order item
          example: "Book"
    OrderSummaryInfo:
      type: object
      readOnly: true
      description: The order summary information
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the order
          example: "019622e7-87ac-7bd1-aa9c-35803d8a1e50"
        status:
          "$ref": "#/components/schemas/Status"
        totalPrice:
          type: number
          format: double
          description: The total price of the order
          example: 100.00
    PagedResultOfBuyerDto:
      type: object
      readOnly: true
      description: The paged result of the buyer
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/BuyerDto"
        pageIndex:
          type: integer
          format: int32
          description: The page index
          example: 1
        pageSize:
          type: integer
          format: int32
          description: The page size
          example: 10
        totalItems:
          type: integer
          format: int64
          description: The total items
          example: 100
        totalPages:
          type: number
          format: double
          description: The total pages
          example: 10
        hasPreviousPage:
          type: boolean
          description: The has previous page
          example: true
        hasNextPage:
          type: boolean
          description: The has next page
          example: true
    PagedResultOfOrderDto:
      type: object
      readOnly: true
      description: The paged result of the order
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/OrderDto"
        pageIndex:
          type: integer
          format: int32
          description: The page index
          example: 1
        pageSize:
          type: integer
          format: int32
          description: The page size
          example: 10
        totalItems:
          type: integer
          format: int64
          description: The total items
          example: 100
        totalPages:
          type: number
          format: double
          description: The total pages
          example: 10
        hasPreviousPage:
          type: boolean
          description: The has previous page
          example: true
        hasNextPage:
          type: boolean
          description: The has next page
          example: true
    ProblemDetails:
      type: object
      readOnly: true
      x-scalar-ignore: true
      description: RFC 9110 (https://tools.ietf.org/html/rfc9110)
      properties:
        type:
          type: string
          description: The type of the problem
          example: "https://tools.ietf.org/html/rfc9110#section-15.5.1"
        title:
          type: string
          description: The title of the problem
          example: "Not Found"
        status:
          type: integer
          format: int32
          description: The status code of the problem
          example: 404
        detail:
          type: string
          description: The detail of the problem
          example: "Buyer with id 019622d7-e45c-7ccb-868f-509b69559883 not found."
    Status:
      description: The status of the order
      enum:
        - New
        - Cancelled
        - Completed
    UpdateAddressCommand:
      required:
        - street
        - city
        - province
      type: object
      writeOnly: true
      description: The command to update the address of the buyer
      properties:
        street:
          type: string
          description: The street of the buyer
          maxLength: 50
          example: "123 Main St"
        city:
          type: string
          description: The city of the buyer
          maxLength: 50
          example: "Anytown"
        province:
          type: string
          description: The province of the buyer
          maxLength: 50
          example: "CA"
  securitySchemes:
    OAuth:
      type: oauth2
      description: OAuth2 security scheme for the BookWorm API
      flows:
        authorizationCode:
          authorizationUrl: "https://auth.bookworm.com/realms/bookworm/protocol/openid-connect/auth"
          tokenUrl: "https://auth.bookworm.com/realms/bookworm/protocol/openid-connect/token"
          scopes:
            ordering: "Ordering API"
          x-usePkce: "SHA-256"
          x-scalar-client-id: "ordering"
          x-scalar-security-body:
            audience: "account"
tags:
  - name: Buyer
    description: Endpoints for managing buyer information, including profile details, shipping addresses, and purchase history for customers of the BookWorm platform
  - name: Order
    description: Endpoints for managing orders, including creation, retrieval, updating status, and cancellation of orders in the BookWorm e-commerce platform
