# MTPL Policy Service — integration guide (v0 draft)
#
# NOTE FOR WORKSHOP HOSTS: this spec is DELIBERATELY flawed. It describes the
# live API at api.cybernotes.it but hides several things an integrator would
# need. The planted flaws are listed in api/docs/v0-answer-key.md — do not
# "fix" this file, it is the Workshop 2 gap-hunt material.
openapi: 3.0.3
info:
  title: MTPL Policy Service
  version: 0.9-draft
  description: |
    ⚠️ DELIBERATELY FLAWED TEACHING MATERIAL — NOT A REFERENCE SPECIFICATION.

    This draft is published as a Workshop 2 exercise. Do not copy it as a
    template, cite it as an example of good practice, or use it to learn
    OpenAPI conventions. What it leaves out is the point of the exercise, so
    it is not listed here.

    The working specification is at https://api.cybernotes.it/mtpl/docs

    ---

    Integration guide for the MTPL policy service. Create and manage mandatory
    motor liability policies for vehicles. All endpoints exchange JSON.
paths:
  /mtpl/v1/coverage-options:
    get:
      operationId: listCoverageOptions
      summary: List coverage options
      responses:
        "200":
          description: The product list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  options:
                    type: array
                    items:
                      $ref: "#/components/schemas/CoverageOption"
              example:
                options:
                  - code: MTPL-STD
                    name: Mandatory motor liability
                    term: P1Y
  /mtpl/v1/policies:
    get:
      operationId: listPolicies
      summary: List policies
      responses:
        "200":
          description: The policy list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Policy"
                  total:
                    type: integer
    post:
      operationId: createPolicy
      summary: Create a policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyRequest"
            examples:
              plate:
                summary: By vehicle id
                value:
                  vehicleId: ABC-101
                  holder: Demo Holder 01
              vin:
                summary: By vehicle id
                value:
                  vehicleId: 5TDEM000000000103
                  holder: Demo Holder 03
      responses:
        "201":
          description: Policy created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
  /mtpl/v1/policies/{policyId}:
    parameters:
      - name: policyId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getPolicy
      summary: Get a policy
      responses:
        "200":
          description: The policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
        "404":
          description: No such policy.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
              example:
                type: https://api.cybernotes.it/problems/not-found
                title: Policy not found
                status: 404
    put:
      operationId: updatePolicy
      summary: Update a policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyRequest"
      responses:
        "200":
          description: The updated policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
  /mtpl/v1/policies/{policyId}/cancel:
    post:
      operationId: cancelPolicy
      summary: Cancel a policy
      parameters:
        - name: policyId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The cancelled policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
  /mtpl/v1/limited/ping:
    get:
      operationId: ping
      summary: Connectivity check
      responses:
        "200":
          description: Pong.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ping:
                    type: string
              example:
                ping: pong
  /mtpl/v1/signed/policy-check:
    post:
      operationId: policyCheck
      summary: Check whether a vehicle is insured
      parameters:
        - name: X-Signature
          in: header
          required: true
          description: Hex HMAC-SHA256 of the request body.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vehicleId:
                  type: string
            example:
              vehicleId: ABC-101
      responses:
        "200":
          description: Register lookup result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vehicleId:
                    type: string
                  inForce:
                    type: boolean
                  policyId:
                    type: string
                    nullable: true
components:
  schemas:
    CoverageOption:
      type: object
      properties:
        code:
          type: string
          example: MTPL-STD
        name:
          type: string
          example: Mandatory motor liability
        term:
          type: string
          example: P1Y
    PolicyRequest:
      type: object
      required:
        - vehicleId
      properties:
        vehicleId:
          type: string
          description: The vehicle identifier.
          example: ABC-101
        holder:
          type: string
          example: Demo Holder 01
    Policy:
      type: object
      properties:
        id:
          type: string
          example: pol-demo-0001
        productCode:
          type: string
          example: MTPL-STD
        vehicleId:
          type: string
          example: 5TDEM000000000101
        holder:
          type: string
          example: Demo Holder 01
        status:
          type: string
          enum: [active, updated, cancelled, expired]
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Problem:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
