Koha Swagger conf

{
  "swagger": "2.0",
  "info": {
    "title": "Koha REST API",
    "version": "1",
    "license": {
      "name": "GPL v3",
      "url": "http://www.gnu.org/licenses/gpl.txt"
    },
    "contact": {
      "name": "Koha Team",
      "url": "http://koha-community.org/"
    }
  },
  "basePath": "/v1",
  "paths": {
    "/borrowers": {
      "get": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers",
        "x-koha-permission": {
          "borrowers": "*"
        },
        "operationId": "listBorrowers",
        "tags": ["borrowers"],
        "summary": "just a summary",
        "description": "long description",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A list of borrowers",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/borrower"
              }
            }
          }
        },
        "security": [
          { "multi_key_auth": [] }
        ]
      }
    },
    "/borrowers/{borrowernumber}": {
      "get": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers",
        "x-koha-permission": {
          "borrowers": "*"
        },
        "operationId": "getBorrower",
        "tags": ["borrowers"],
        "parameters": [
          {
            "$ref": "#/parameters/borrowernumberPathParam"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A borrower",
            "schema": {
              "$ref": "#/definitions/borrower"
            }
          },
          "404": {
            "description": "Borrower not found",
            "schema": {
              "$ref": "#/definitions/error"
            }
          }
        },
        "security": [
          { "multi_key_auth": [] }
        ]
      }
    },
    "/borrowers/{borrowernumber}/issues": {
      "get": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers::Issues",
        "operationId": "listBorrowerIssues",
        "tags": ["borrowers", "issues"],
        "parameters": [
          {
            "$ref": "#/parameters/borrowernumberPathParam"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A list of issues",
            "schema": {
              "$ref": "#/definitions/issues"
            }
          },
          "404": {
            "description": "Borrower not found",
            "schema": {
              "$ref": "#/definitions/error"
            }
          }
        }
      }
    },
    "/borrowers/{borrowernumber}/issues/{itemnumber}": {
      "get": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers::Issues",
        "operationId": "getBorrowerIssue",
        "tags": ["borrowers", "issues"],
        "parameters": [
          { "$ref": "#/parameters/borrowernumberPathParam" },
          { "$ref": "#/parameters/itemnumberPathParam" }
        ],
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": "Updated borrower's issue",
            "schema": { "$ref": "#/definitions/issue" }
          },
          "404": {
            "description": "Issue not found",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      },
      "put": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers::Issues",
        "operationId": "renewBorrowerIssue",
        "tags": ["borrowers", "issues"],
        "parameters": [
          { "$ref": "#/parameters/borrowernumberPathParam" },
          { "$ref": "#/parameters/itemnumberPathParam" }
        ],
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": "Updated borrower's issue",
            "schema": { "$ref": "#/definitions/issue" }
          },
          "403": {
            "description": "Cannot renew issue",
            "schema": { "$ref": "#/definitions/error" }
          },
          "404": {
            "description": "Issue not found",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      }
    },
    "/borrowers/{borrowernumber}/reserves": {
      "get": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers::Reserves",
        "operationId": "listBorrowerReserves",
        "tags": ["borrowers", "reserves"],
        "parameters": [
          { "$ref": "#/parameters/borrowernumberPathParam" }
        ],
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": "A list of reserves",
            "schema": { "$ref": "#/definitions/reserves" }
          },
          "404": {
            "description": "Borrower not found",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      },
      "post": {
        "x-mojo-controller": "Koha::REST::V1::Borrowers::Reserves",
        "operationId": "addBorrowerReserve",
        "tags": ["borrowers", "reserves"],
        "parameters": [
          { "$ref": "#/parameters/borrowernumberPathParam" },
          {
            "name": "body",
            "in": "body",
            "description": "A JSON object containing informations about the new reserve",
            "required": true,
            "schema": { "$ref": "#/definitions/newBorrowerReserveBody" }
          }
        ],
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "responses": {
          "201": {
            "description": "Created reserve",
            "schema": { "$ref": "#/definitions/reserve" }
          },
          "400": {
            "description": "Missing or wrong parameters",
            "schema": { "$ref": "#/definitions/error" }
          },
          "403": {
            "description": "Reserve not allowed",
            "schema": { "$ref": "#/definitions/error" }
          },
          "404": {
            "description": "Borrower not found",
            "schema": { "$ref": "#/definitions/error" }
          },
          "500": {
            "description": "Internal error",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      }
    },
    "/reserves/{reserve_id}": {
      "put": {
        "x-mojo-controller": "Koha::REST::V1::Reserves",
        "operationId": "editReserve",
        "tags": ["reserves"],
        "parameters": [
          { "$ref": "#/parameters/reserveIdPathParam" },
          {
            "name": "body",
            "in": "body",
            "description": "A JSON object containing fields to modify",
            "required": true,
            "schema": { "$ref": "#/definitions/editReserveBody" }
          }
        ],
        "consumes": ["application/json"],
        "produces": ["application/json"],
        "responses": {
          "200": {
            "description": "Updated reserve",
            "schema": { "$ref": "#/definitions/reserve" }
          },
          "400": {
            "description": "Missing or wrong parameters",
            "schema": { "$ref": "#/definitions/error" }
          },
          "404": {
            "description": "Reserve not found",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      },
      "delete": {
        "x-mojo-controller": "Koha::REST::V1::Reserves",
        "operationId": "deleteReserve",
        "tags": ["reserves"],
        "parameters": [
          { "$ref": "#/parameters/reserveIdPathParam" }
        ],
        "produces": ["application/json"],
        "responses": {
          "204": {
            "description": "No content",
            "schema": {
              "type": "null"
            }
          },
          "404": {
            "description": "Reserve not found",
            "schema": { "$ref": "#/definitions/error" }
          }
        }
      }
    }
  },
  "definitions": {
    "borrower": {
      "type": "object",
      "properties": {
        "borrowernumber": {
          "$ref": "#/definitions/borrowernumber"
        },
        "cardnumber": {
          "description": "library assigned ID number for borrowers"
        },
        "surname": {
          "description": "borrower's last name"
        },
        "firstname": {
          "description": "borrower's first name"
        }
      }
    },
    "issues": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/issue"
      }
    },
    "issue": {
      "type": "object",
      "properties": {
        "borrowernumber": {
          "$ref": "#/definitions/borrowernumber"
        },
        "itemnumber": {
          "$ref": "#/definitions/itemnumber"
        },
        "date_due": {
          "description": "Due date"
        },
        "branchcode": {
          "$ref": "#/definitions/branchcode"
        },
        "issuingbranch": {
          "description": "Code of the branch where issue was made"
        },
        "returndate": {
          "description": "Date the item was returned"
        },
        "lastreneweddate": {
          "description": "Date the item was last renewed"
        },
        "return": {
          "description": "?"
        },
        "renewals": {
          "description": "Number of renewals"
        },
        "auto_renew": {
          "description": "Auto renewal"
        },
        "timestamp": {
          "description": "Last update time"
        },
        "issuedate": {
          "description": "Date the item was issued"
        },
        "onsite_checkout": {
          "description": "On site checkout"
        }
      }
    },
    "reserves": {
      "type": "array",
      "items": { "$ref": "#/definitions/reserve" }
    },
    "reserve": {
      "type": "object",
      "properties": {
        "reserve_id": {
          "description": "Internal reserve identifier"
        },
        "borrowernumber": { "$ref" : "#/definitions/borrowernumber" },
        "reservedate": {
          "description": "the date the reserve was placed"
        },
        "biblionumber": { "$ref": "#/definitions/biblionumber" },
        "constrainttype": {
          "description": "type of constraint"
        },
        "branchcode": { "$ref": "#/definitions/branchcode" },
        "notificationdate": {
          "description": "currently unused"
        },
        "reminderdate": {
          "description": "currently unused"
        },
        "cancellationdate": {
          "description": "the date the reserve was cancelled"
        },
        "reservenotes": {
          "description": "notes related to this reserve"
        },
        "priority": {
          "description": "where in the queue the patron sits"
        },
        "found": {
          "description": "a one letter code defining what the status of the reserve is after it has been confirmed"
        },
        "timestamp": {
          "description": "date and time the reserve was last updated"
        },
        "itemnumber": { "$ref": "#/definitions/itemnumber" },
        "waitingdate": {
          "description": "the date the item was marked as waiting for the patron at the library"
        },
        "expirationdate": {
          "description": "the date the reserve expires"
        },
        "lowestPriority": {
          "description": ""
        },
        "suspend": {
          "description": ""
        },
        "suspend_until": {
          "description": ""
        }
      }
    },
    "newBorrowerReserveBody": {
      "type": "object",
      "properties": {
        "biblionumber": {
          "description": "Biblio internal identifier",
          "type": "integer"
        },
        "itemnumber": {
          "description": "Item internal identifier",
          "type": "integer"
        },
        "branchcode": {
          "description": "Pickup location",
          "type": "string",
          "required": true
        },
        "expirationdate": {
          "description": "Reserve end date",
          "type": "string",
          "format": "date"
        }
      }
    },
    "editReserveBody": {
      "type": "object",
      "properties": {
        "priority": {
          "description": "Position in waiting queue",
          "type": "integer",
          "minimum": 1
        },
        "branchcode": {
          "description": "Pickup location",
          "type": "string"
        },
        "suspend_until": {
          "description": "Suspend until",
          "type": "string",
          "format": "date"
        }
      }
    },
    "biblionumber": {
      "description": "Biblio internal identifier"
    },
    "borrowernumber": {
      "description": "Borrower internal identifier"
    },
    "branchcode": {
      "description": "Branch code"
    },
    "itemnumber": {
      "description": "Item internal identifier"
    },
    "error": {
      "type": "object",
      "properties": {
        "error": {
          "description": "Error message",
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "borrowernumberPathParam": {
      "name": "borrowernumber",
      "in": "path",
      "description": "Internal borrower identifier",
      "required": true,
      "type": "integer"
    },
    "reserveIdPathParam": {
      "name": "reserve_id",
      "in": "path",
      "description": "Internal reserve identifier",
      "required": true,
      "type": "integer"
    },
    "itemnumberPathParam": {
      "name": "itemnumber",
      "in": "path",
      "description": "Internal item identifier",
      "required": "true",
      "type": "integer"
    }
  },
  "securityDefinitions": {
    "multi_key_auth": {
      "type": "custom",
      "in": "header",
      "keys": {
        "ETag": {
          "type": "dateTime",
          "description": "The current time when the request is created."
        },
        "x-koha-username": {
          "type": "string",
          "description": "The username of the API consumer. Not the library card's barcode or borrowernumber!"
        },
        "x-koha-permission": {
          "type": "string",
          "description": "The specific permission the user must have. Eg. 'circulation => force_checkout'"
        },
        "x-koha-signature": {
          "type": "string",
          "description": "The signature is a HMAC-SHA256 hash of several elements of the request, separated by spaces: 1. HTTP method (uppercase) 2. URL path and query string 3. Value of x-koha-username -header 4. Value of the ETag-header"
        }
      }
    }
  }
}