Example Swagger 2.0 JSON file for a Bill Payment API with 10 entries (endpoints):

docs.bill-payment-api.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "Bill Payment API",
    "description": "Facilitate bill payments for various services and utilities.",
    "version": "1.0.0"
  },
  "basePath": "/api",
  "schemes": ["http", "https"],
  "paths": {
    "/billers/list": {
      "get": {
        "summary": "List Billers",
        "description": "Endpoint to get the list of available billers.",
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": "Successful response",
            "schema": {
              "$ref": "#/definitions/BillerList"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          }
        }
      }
    },
    "/bills/pay": {
      "post": {
        "summary": "Pay Bill",
        "description": "Endpoint to initiate a bill payment.",
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "parameters": [
          {
            "in": "body",
            "name": "billPaymentData",
            "description": "Bill payment data",
            "schema": {
              "$ref": "#/definitions/BillPaymentData"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bill payment successful",
            "schema": {
              "$ref": "#/definitions/BillPaymentResult"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          },
          "404": {
            "description": "Biller not found",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          }
        }
      }
    },
    "/bills/schedule": {
      "post": {
        "summary": "Schedule Bill Payment",
        "description": "Endpoint to schedule a bill payment for a future date.",
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "parameters": [
          {
            "in": "body",
            "name": "scheduledBillPaymentData",
            "description": "Scheduled bill payment data",
            "schema": {
              "$ref": "#/definitions/ScheduledBillPaymentData"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bill payment scheduled successfully",
            "schema": {
              "$ref": "#/definitions/BillPaymentResult"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          },
          "404": {
            "description": "Biller not found",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          }
        }
      }
    },
    "/bills/history/{customerId}": {
      "get": {
        "summary": "Get Bill Payment History",
        "description": "Endpoint to get the bill payment history for a specific customer.",
        "produces": ["application/json"],
        "parameters": [
          {
            "in": "path",
            "name": "customerId",
            "type": "string",
            "description": "ID of the customer for bill payment history retrieval."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "schema": {
              "$ref": "#/definitions/BillPaymentHistory"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          },
          "404": {
            "description": "Not found",
            "schema": {
              "$ref": "#/definitions/ErrorModel"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ErrorModel": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "description": "Error message."
        }
      }
    },
    "Biller": {
      "type": "object",
      "properties": {
        "billerId": {
          "type": "string",
          "description": "ID of the biller."
        },
        "name": {
          "type": "string",
          "description": "Name of the biller."
        },
        "category": {
          "type": "string",
          "description": "Category of the biller (e.g., utilities, telecom)."
        }
      }
    },
    "BillerList": {
      "type": "object",
      "properties": {
        "billers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Biller"
          },
          "description": "List of available billers."
        }
      }
    },
    "BillPaymentData": {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "description": "ID of the customer initiating the bill payment."
        },
        "billerId": {
          "type": "string",
          "description": "ID of the biller for the payment."
        },
        "amount": {
          "type": "number",
          "description": "Amount to be paid for the bill."
        }
      },
      "required": ["customerId", "billerId", "amount"]
    },
    "ScheduledBillPaymentData": {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "description": "ID of the customer scheduling the bill payment."
        },
        "billerId": {
          "type": "string",
          "description": "ID of the biller for the payment."
        },
        "amount": {
          "type": "number",
          "description": "Amount to be paid for the bill."
        },
        "scheduledDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time for the scheduled payment."
        }
      },
      "required": ["customerId", "billerId", "amount", "scheduledDate"]
    },
    "BillPaymentResult": {
      "type": "object",
      "properties": {
        "paymentId": {
          "type": "string",
          "description": "ID of the bill payment."
        },
        "amount": {
          "type": "number",
          "description": "Amount paid for the bill."
        },
        "status": {
          "type": "string",
          "description": "Payment status (e.g., success, pending)."
        }
      }
    },
    "BillPaymentHistory": {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "description": "ID of the customer for bill payment history retrieval."
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BillPaymentResult"
          },
          "description": "List of bill payment history entries."
        }
      }
    }
  }
}