Merge pull request #2681 from sunhoww/update_swagger

Update swagger documentation

2 files changed, 721 insertions, 675 deletions

diff --git a/swagger.json b/swagger.json
index 25b76963c..0f298f161 100644
--- a/swagger.json
+++ b/swagger.json
@@ -1,23 +1,29 @@
 {
     "swagger": "2.0",
     "info": {
-        "version": "3.8",
+        "version": "3.9",
         "title": "traccar"
     },
-    "host": "traccar.org",
+    "host": "demo.traccar.org",
     "basePath": "/api",
     "schemes": [
         "http"
     ],
+    "security": [
+        {
+            "basicAuth": []
+        }
+    ],
+    "consumes": [
+        "application/json"
+    ],
+    "produces": [
+        "application/json"
+    ],
     "paths": {
         "/commands": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Dispatch commands to device",
                 "parameters": [
                     {
                         "name": "body",
@@ -31,70 +37,53 @@
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Command"
                         }
+                    },
+                    "400": {
+                        "description": "Could happen when dispatching to a device that is offline, the user doesn't have permission or an incorrect command _type_ for the device"
                     }
                 }
             }
         },
         "/devices": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Devices",
+                "description": "Without any params, returns a list of the user's devices",
                 "parameters": [
                     {
-                        "name": "all",
-                        "in": "query",
-                        "required": true,
-                        "type": "boolean"
+                        "$ref": "#/parameters/all"
                     },
                     {
-                        "name": "userId",
-                        "in": "query",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/userId"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
                                 "$ref": "#/definitions/Device"
                             }
                         }
+                    },
+                    "400": {
+                      "description": "No permission"
                     }
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Create a Device",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Device"
-                        }
+                        "$ref": "#/parameters/Device"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Device"
                         }
@@ -104,32 +93,18 @@
         },
         "/devices/{id}": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update a Device",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Device"
-                        }
+                        "$ref": "#/parameters/Device"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Device"
                         }
@@ -137,42 +112,25 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update a Device",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/devices/{id}/distance": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update the distance counter of the Device",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
                         "name": "body",
@@ -185,34 +143,22 @@
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/devices/geofences": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Link a Geofence to a Device",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/DeviceGeofence"
-                        }
+                        "$ref": "#/parameters/DeviceGeofence"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/DeviceGeofence"
                         }
@@ -220,56 +166,34 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Remove a Geofence from a Device",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/DeviceGeofence"
-                        }
+                        "$ref": "#/parameters/DeviceGeofence"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/groups": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Groups",
+                "description": "Without any params, returns a list of the Groups the user belongs to",
                 "parameters": [
                     {
-                        "name": "all",
-                        "in": "query",
-                        "required": true,
-                        "type": "boolean"
+                        "$ref": "#/parameters/all"
                     },
                     {
-                        "name": "userId",
-                        "in": "query",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/userId"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -280,61 +204,39 @@
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Create a Group",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Group"
-                        }
+                        "$ref": "#/parameters/Group"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Group"
                         }
+                    },
+                    "400": {
+                      "description": "No permission"
                     }
                 }
             }
         },
         "/groups/{id}": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update a Group",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Group"
-                        }
+                        "$ref": "#/parameters/Group"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Group"
                         }
@@ -342,50 +244,30 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Delete a Group",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/groups/geofences": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Link a Geofence to a Group",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GroupGeofence"
-                        }
+                        "$ref": "#/parameters/GroupGeofence"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/GroupGeofence"
                         }
@@ -393,105 +275,64 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Remove a Geofence from a Group",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GroupGeofence"
-                        }
+                        "$ref": "#/parameters/GroupGeofence"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/permissions/devices": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Link a Device to a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/DevicePermission"
-                        }
+                        "$ref": "#/parameters/DevicePermission"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/DevicePermission"
                         }
+                    },
+                    "400": {
+                      "description": "No permission"
                     }
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Remove a Device from a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/DevicePermission"
-                        }
+                        "$ref": "#/parameters/DevicePermission"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/permissions/groups": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Link a Group to a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GroupPermission"
-                        }
+                        "$ref": "#/parameters/GroupPermission"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/GroupPermission"
                         }
@@ -499,52 +340,30 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Remove a Group from a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GroupPermission"
-                        }
+                        "$ref": "#/parameters/GroupPermission"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/permissions/geofences": {
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Link a Geofence to a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GeofencePermission"
-                        }
+                        "$ref": "#/parameters/GeofencePermission"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/GeofencePermission"
                         }
@@ -552,26 +371,15 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Remove a Geofence from a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/GeofencePermission"
-                        }
+                        "$ref": "#/parameters/GeofencePermission"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
@@ -579,13 +387,7 @@
         "/positions": {
             "get": {
                 "summary" : "Fetches a list of Positions",
-                "description" : "Without any params, it returns a list of last known positions for all the user's devices",
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "description" : "Without any params, it returns a list of last known positions for all the user's Devices. _from_ and _to_ fields are not required with _id_",
                 "parameters": [
                     {
                         "name": "deviceId",
@@ -597,17 +399,20 @@
                     {
                         "name": "from",
                         "in": "query",
-                        "description": "Not required with _id_",
+                        "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`",
                         "required": false,
-                        "type": "string"
+                        "type": "string",
+                        "format": "date-time"
                     },
                     {
                         "name": "to",
                         "in": "query",
-                        "description": "Not required with _id_",
+                        "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`",
                         "required": false,
-                        "type": "string"
-                    }, {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    {
                         "name" : "id",
                         "in" : "query",
                         "description" : "To fetch one or more positions. Multiple params can be passed like `id=31&id=42`",
@@ -631,17 +436,10 @@
         },
         "/server": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
-                "parameters": [],
+                "summary": "Fetch Server information",
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Server"
                         }
@@ -649,12 +447,7 @@
                 }
             },
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update Server information",
                 "parameters": [
                     {
                         "name": "body",
@@ -668,7 +461,6 @@
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Server"
                         }
@@ -678,34 +470,27 @@
         },
         "/session": {
             "get": {
+                "summary": "Fetch Session information",
                 "consumes": [
                     "application/x-www-form-urlencoded"
                 ],
-                "produces": [
-                    "application/json"
-                ],
-                "parameters": [],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/User"
                         }
                     },
                     "404": {
-                        "description": "Not Found",
-                        "headers": {}
+                        "description": "Not Found"
                     }
                 }
             },
             "post": {
+                "summary": "Create a new Session",
                 "consumes": [
                     "application/x-www-form-urlencoded"
                 ],
-                "produces": [
-                    "application/json"
-                ],
                 "parameters": [
                     {
                         "name": "email",
@@ -717,82 +502,63 @@
                         "name": "password",
                         "in": "formData",
                         "required": true,
-                        "type": "string"
+                        "type": "string",
+                        "format": "password"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/User"
                         }
                     },
                     "401": {
-                        "description": "Unauthorized",
-                        "headers": {}
+                        "description": "Unauthorized"
                     }
                 }
             },
             "delete": {
+                "summary": "Close the Session",
                 "consumes": [
                     "application/x-www-form-urlencoded"
                 ],
-                "produces": [
-                    "application/json"
-                ],
                 "parameters": [],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/users": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
-                "parameters": [],
+                "summary": "Fetch a list of Users",
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
                                 "$ref": "#/definitions/User"
                             }
                         }
+                    },
+                    "400": {
+                        "description": "No Permission"
                     }
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Create a User",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/User"
-                        }
+                        "$ref": "#/parameters/User"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/User"
                         }
@@ -802,32 +568,18 @@
         },
         "/users/{id}": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update a User",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/User"
-                        }
+                        "$ref": "#/parameters/User"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/User"
                         }
@@ -835,54 +587,37 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Delete a User",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/users/notifications": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Notification types",
+                "description": "Without params, it returns a list of the user's enabled Notifications",
                 "parameters": [
                     {
                         "name": "all",
                         "in": "query",
-                        "required": true,
+                        "description": "To fetch a list of all available Notifications",
                         "type": "boolean"
                     },
                     {
-                        "name": "userId",
-                        "in": "query",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/userId"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -893,12 +628,7 @@
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Set or unset a Notification",
                 "parameters": [
                     {
                         "name": "body",
@@ -912,7 +642,6 @@
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Notification"
                         }
@@ -922,12 +651,7 @@
         },
         "/commandtypes": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of available Commands for the Device",
                 "parameters": [
                     {
                         "name": "deviceId",
@@ -939,49 +663,37 @@
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
                                 "$ref": "#/definitions/CommandType"
                             }
                         }
+                    },
+                    "400": {
+                        "description": "Could happen when trying to fetch from an offline device or the user does not have permission"
                     }
                 }
             }
         },
         "/geofences": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Geofences",
+                "description": "Without params, it returns a list of Geofences the user has access to",
                 "parameters": [
                     {
-                        "name": "all",
-                        "in": "query",
-                        "required": true,
-                        "type": "boolean"
+                        "$ref": "#/parameters/all"
                     },
                     {
-                        "name": "userId",
-                        "in": "query",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/userId"
                     },
                     {
                         "name": "groupId",
                         "in": "query",
-                        "required": true,
                         "type": "integer"
                     },
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/deviceId"
                     },
                     {
                         "name": "refresh",
@@ -993,7 +705,6 @@
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1004,26 +715,15 @@
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Create a Geofence",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Geofence"
-                        }
+                        "$ref": "#/parameters/Geofence"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Geofence"
                         }
@@ -1033,32 +733,18 @@
         },
         "/geofences/{id}": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update a Geofence",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/Geofence"
-                        }
+                        "$ref": "#/parameters/Geofence"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Geofence"
                         }
@@ -1066,48 +752,29 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Delete a Geofence",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
         },
         "/events/{id}": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/Event"
                         }
@@ -1117,50 +784,25 @@
         },
         "/reports/route": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Positions within the time period for the Devices or Groups",
+                "description": "At least one _deviceId_ or one _groupId_ must be passed",
                 "parameters": [
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/deviceIdArray"
                     },
                     {
-                        "name": "groupId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/groupIdArray"
                     },
                     {
-                        "name": "from",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/fromTime"
                     },
                     {
-                        "name": "to",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/toTime"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1173,60 +815,34 @@
         },
         "/reports/events": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of Events within the time period for the Devices or Groups",
+                "description": "At least one _deviceId_ or one _groupId_ must be passed",
                 "parameters": [
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/deviceIdArray"
                     },
                     {
-                        "name": "groupId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/groupIdArray"
                     },
                     {
                         "name": "type",
                         "in": "query",
                         "description": "% can be used to return events of all types",
-                        "required": true,
                         "type": "array",
                         "items": {
                             "type": "string"
                         }
                     },
                     {
-                        "name": "from",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/fromTime"
                     },
                     {
-                        "name": "to",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/toTime"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1239,50 +855,25 @@
         },
         "/reports/summary": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of ReportSummary within the time period for the Devices or Groups",
+                "description": "At least one _deviceId_ or one _groupId_ must be passed",
                 "parameters": [
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/deviceIdArray"
                     },
                     {
-                        "name": "groupId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/groupIdArray"
                     },
                     {
-                        "name": "from",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/fromTime"
                     },
                     {
-                        "name": "to",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/toTime"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1295,50 +886,25 @@
         },
         "/reports/trips": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of ReportTrips within the time period for the Devices or Groups",
+                "description": "At least one _deviceId_ or one _groupId_ must be passed",
                 "parameters": [
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/deviceIdArray"
                     },
                     {
-                        "name": "groupId",
-                        "in": "query",
-                        "description": "at least one deviceId or one groupId must be passed",
-                        "required": true,
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
+                        "$ref": "#/parameters/groupIdArray"
                     },
                     {
-                        "name": "from",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/fromTime"
                     },
                     {
-                        "name": "to",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/toTime"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1351,30 +917,18 @@
         },
         "/statistics": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch server Statistics",
                 "parameters": [
                     {
-                        "name": "from",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/fromTime"
                     },
                     {
-                        "name": "to",
-                        "in": "query",
-                        "required": true,
-                        "type": "string"
+                        "$ref": "#/parameters/toTime"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1387,24 +941,16 @@
         },
         "/attributes/aliases": {
             "get": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Fetch a list of AttributeAlias",
+                "description": "Without params, it returns a list of AttributeAlias from all the user's Devices",
                 "parameters": [
                     {
-                        "name": "deviceId",
-                        "in": "query",
-                        "required": false,
-                        "type": "integer"
+                        "$ref": "#/parameters/deviceId"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "type": "array",
                             "items": {
@@ -1415,26 +961,15 @@
                 }
             },
             "post": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Set an AttributeAlias",
                 "parameters": [
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/AttributeAlias"
-                        }
+                        "$ref": "#/parameters/AttributeAlias"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/AttributeAlias"
                         }
@@ -1444,32 +979,18 @@
         },
         "/attributes/aliases/{id}": {
             "put": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Update an AttributeAlias",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     },
                     {
-                        "name": "body",
-                        "in": "body",
-                        "required": true,
-                        "schema": {
-                            "$ref": "#/definitions/AttributeAlias"
-                        }
+                        "$ref": "#/parameters/AttributeAlias"
                     }
                 ],
                 "responses": {
                     "200": {
                         "description": "OK",
-                        "headers": {},
                         "schema": {
                             "$ref": "#/definitions/AttributeAlias"
                         }
@@ -1477,24 +998,15 @@
                 }
             },
             "delete": {
-                "consumes": [
-                    "application/json"
-                ],
-                "produces": [
-                    "application/json"
-                ],
+                "summary": "Delete an AttributeAlias",
                 "parameters": [
                     {
-                        "name": "id",
-                        "in": "path",
-                        "required": true,
-                        "type": "integer"
+                        "$ref": "#/parameters/entityId"
                     }
                 ],
                 "responses": {
                     "204": {
-                        "description": "No Content",
-                        "headers": {}
+                        "description": "No Content"
                     }
                 }
             }
@@ -1513,10 +1025,19 @@
                     "type": "string"
                 },
                 "deviceTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "fixTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
+                },
+                "serverTime": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "outdated": {
                     "type": "boolean"
@@ -1534,7 +1055,8 @@
                     "type": "number"
                 },
                 "speed": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in knots"
                 },
                 "course": {
                     "type": "number"
@@ -1593,7 +1115,9 @@
                     "type": "boolean"
                 },
                 "expirationTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "deviceLimit": {
                     "type": "integer"
@@ -1680,7 +1204,9 @@
                     "type": "string"
                 },
                 "lastUpdate": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "positionId": {
                     "type": "integer"
@@ -1700,7 +1226,12 @@
                 "category": {
                     "type": "string"
                 },
-                "geofenceIds": {},
+                "geofenceIds": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                },
                 "attributes": {}
             }
         },
@@ -1815,7 +1346,9 @@
                     "type": "string"
                 },
                 "serverTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "deviceId": {
                     "type": "integer"
@@ -1838,13 +1371,16 @@
                     "type": "string"
                 },
                 "maxSpeed": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in knots"
                 },
                 "averageSpeed": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in knots"
                 },
                 "distance": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in meters"
                 },
                 "engineHours": {
                     "type": "integer"
@@ -1860,19 +1396,24 @@
                     "type": "string"
                 },
                 "maxSpeed": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in knots"
                 },
                 "averageSpeed": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in knots"
                 },
                 "distance": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in meters"
                 },
                 "duration": {
                     "type": "integer"
                 },
                 "startTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "startAddress": {
                     "type": "string"
@@ -1884,7 +1425,9 @@
                     "type": "number"
                 },
                 "endTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "endAddress": {
                     "type": "string"
@@ -1900,7 +1443,9 @@
         "Statistics": {
             "properties": {
                 "captureTime": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`"
                 },
                 "activeUsers": {
                     "type": "integer"
@@ -1941,9 +1486,156 @@
                     "type": "integer"
                 },
                 "totalDistance": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "in meters"
                 }
             }
         }
+    },
+    "parameters": {
+        "entityId": {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "type": "integer"
+        },
+        "all": {
+            "name": "all",
+            "in": "query",
+            "description": "Can only be used by admin users to fetch all entities",
+            "type": "boolean"
+        },
+        "userId": {
+            "name": "userId",
+            "in": "query",
+            "description": "Standard users can use this only with their own _userId_",
+            "type": "integer"
+        },
+        "deviceId": {
+            "name": "deviceId",
+            "in": "query",
+            "description": "Standard users can use this only with _userId_s, they have access to",
+            "type": "integer"
+        },
+        "Device": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/Device"
+            }
+        },
+        "DeviceGeofence": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/DeviceGeofence"
+            }
+        },
+        "Group": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/Group"
+            }
+        },
+        "GroupGeofence": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/GroupGeofence"
+            }
+        },
+        "DevicePermission": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/DevicePermission"
+            }
+        },
+        "GroupPermission": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/GroupPermission"
+            }
+        },
+        "GeofencePermission": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/GeofencePermission"
+            }
+        },
+        "User": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/User"
+            }
+        },
+        "Geofence": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/Geofence"
+            }
+        },
+        "AttributeAlias": {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+                "$ref": "#/definitions/AttributeAlias"
+            }
+        },
+        "deviceIdArray": {
+            "name": "deviceId",
+            "in": "query",
+            "type": "array",
+            "items": {
+                "type": "integer"
+            },
+            "collectionFormat": "multi"
+        },
+        "groupIdArray": {
+            "name": "groupId",
+            "in": "query",
+            "type": "array",
+            "items": {
+                "type": "integer"
+            },
+            "collectionFormat": "multi"
+        },
+        "fromTime": {
+            "name": "from",
+            "in": "query",
+            "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`",
+            "required": true,
+            "type": "string",
+            "format": "date-time"
+        },
+        "toTime": {
+            "name": "to",
+            "in": "query",
+            "description": "in IS0 8601 format. eg. `1963-11-22T18:30:00Z`",
+            "required": true,
+            "type": "string",
+            "format": "date-time"
+        }
+    },
+    "securityDefinitions": {
+        "basicAuth": {
+            "type": "basic",
+            "description": "Basic HTTP authorization with _email_ and _password_"
+        }
     }
 }
diff --git a/tools/swagger2html.py b/tools/swagger2html.py
new file mode 100755
index 000000000..a3488835c
--- /dev/null
+++ b/tools/swagger2html.py
@@ -0,0 +1,354 @@
+#!/usr/bin/python
+
+import sys, argparse, json, re
+
+def handleException(etype, e=None):
+    if etype == 'KeyError':
+        print "Error: Required property {} not found".format(e)
+    elif etype == 'IOError':
+        print "Error ({}): {}".format(e.errno, e.strerror)
+    elif etype == 'ValueError':
+        print "Error: Unable to parse input as JSON"
+    elif etype == 'Custom':
+        print e
+    sys.exit(1)
+
+def get_json(filename):
+    try:
+        with open(filename) as json_file:
+            json_data = json.load(json_file)
+            return json_data
+    except IOError as e:
+        handleException('IOError', e)
+    except ValueError:
+        handleException('ValueError')
+    except:
+        print "Unexpected error: {}".format(sys.exc_info()[0])
+        raise
+
+def write_file(filename, body):
+    try:
+        with open(filename, 'w') as md_file:
+            md_file.write(body)
+    except IOError as e:
+        handleException('IOError', e)
+
+def make_header(json_data):
+    try:
+        if not 'swagger' in json_data:
+            raise KeyError
+        info = json_data['info']
+        md = "<h1>{}</h1>\n".format(info['title'])
+        md += "<p>Version: {}</p>\n".format(info['version'])
+        if 'license' in info:
+            md += "<p>License: "
+            license = info['license']
+            if 'url' in license:
+                md += '<a href="{}">{}</a>'.format(license['url'], license['name'])
+            else:
+                md += license['name']
+            md += '</p>\n'
+        if 'contact' in info:
+            contact = info['contact']
+            if 'name' in contact or 'email' in contact:
+                md += '<p>Contact: '
+                if not 'name' in contact:
+                    md += '<a href="mailto:{0}">{0}</a>'.format(contact['email'])
+                elif not 'email' in contact:
+                    md += contact['name']
+                else:
+                    md += '{0} &lt;<a href="mailto:{1}"&gt;{1}</a>'.format(contact['name'], contact['email'])
+                md += '  \n'
+            if 'url' in contact:
+                md += "<p>Website: {}</p>\n".format(contact['url'])
+        if 'termsOfService' in info:
+            md += '<p>Terms of Service: {}</p>\n'.format(info['termsOfService'])
+        if 'host' in json_data:
+            md += '<p>Base URL: '
+            base = json_data['host']
+            if 'basePath' in json_data:
+                base += json_data['basePath']
+            else:
+                base += '/'
+            if 'schemes' in json_data:
+                md += (', ').join(map(
+                    lambda x: '<a href="{0}://{1}">{0}://{1}</a>'.format(x, base),
+                    json_data['schemes']
+                ))
+            else:
+                md += '<a href="{0}">{0}</a>'.format(base)
+            md += '</p>\n'
+        if 'description' in info:
+            md += '<p>Description: {}</p>\n'.format(info['description'])
+        md += '\n'
+        return md
+    except KeyErrori as e:
+        handleException('KeyError', e)
+
+def make_ref(ref):
+    href = ref.split('/')[1:]
+    return '<a href="#{}">{}</a>'.format('_'.join(href), href[-1])
+
+def get_ref(ref, raw):
+    keys = ref.split('/')
+    return raw[keys[1]][keys[2]]
+
+def make_html(s):
+    reg = re.compile(r"[*_]{3}(.+?)[*_]{3}")
+    s = reg.sub(r"<strong><em>\1</em></strong>", s)
+    reg = re.compile(r"[*_]{2}(.+?)[*_]{2}")
+    s = reg.sub(r"<strong>\1</strong>", s)
+    reg = re.compile(r"[*_](.+?)[*_]")
+    s = reg.sub(r"<em>\1</em>", s)
+    reg = re.compile(r"\`(.+?)\`")
+    s = reg.sub(r"<code>\1</code>", s)
+    return s
+
+def make_table(data):
+    md = '<table class="table-bordered">\n'
+    md += '  <thead>\n'
+    md += '    <tr>\n'
+    for col in data[0]:
+        md += '      <td>{}</td>\n'.format(col)
+    md += '    </tr>\n'
+    md += '  </thead>\n'
+    md += '  <tbody>\n'
+    for row in data[1:]:
+        md += '    <tr>\n'
+        for cell in row:
+            md += '      <td>{}</td>\n'.format(cell)
+        md += '    </tr>\n'
+    md += '  </tbody>\n'
+    md += '</table>\n'
+    return md
+
+def make_params_table(itemsraw, raw):
+    items = []
+    for item in itemsraw:
+        if '$ref' in item:
+            items.append(get_ref(item['$ref'], raw))
+        else:
+            items.append(item)
+    try:
+        fields = list(set([]).union(*map(lambda x: x.keys(), items)))
+        row = [ 'Name', 'ParamType' ]
+        if 'description' in fields:
+            row.append('Description')
+        if 'required' in fields:
+            row.append('Required')
+        if 'type' in fields:
+            row.append('DataType')
+        if 'schema' in fields:
+            row.append('Schema')
+        table = [ row ]
+        for item in items:
+            row = [ "<em>{}</em>".format(item['name']), item['in'] ]
+            if 'description' in fields:
+                if 'description' in item:
+                    row.append(make_html(item['description']))
+                else:
+                    row.append('')
+            if 'required' in fields:
+                required = 'False'
+                if 'required' in item and item['required']:
+                    required = "<strong>True</strong>"
+                row.append(required)
+            if 'type' in fields:
+                type = ''
+                if 'type' in item:
+                    if item['type'] == 'array':
+                        type = "[ <em>{}</em> ]".format(item['items']['type'])
+                    else:
+                        type = item['type']
+                        if 'format' in item:
+                            type += " ({})".format(item['format'])
+                        type = "<em>{}</em>".format(type)
+                row.append(type)
+            if 'schema' in fields:
+                if 'schema' in item:
+                    if '$ref' in item['schema']:
+                        row.append(make_ref(item['schema']['$ref']))
+                else:
+                    row.append('')
+            table.append(row)
+        return make_table(table)
+    except KeyError as e:
+        handleException('KeyError', e)
+
+def make_responses_table(responses):
+    try:
+        fields = list(
+            set([]).union(*map(lambda x: x.keys(),
+                map(lambda x: responses[x], responses.keys())
+            ))
+        )
+        row = [ 'Status Code', 'Description' ]
+        if 'headers' in fields:
+            row.append('Headers')
+        if 'schema' in fields:
+            row.append('Schema')
+        if 'examples' in fields:
+            row.append('Examples')
+        table = [ row ]
+        for key in sorted(responses):
+            response = responses[key]
+            row = [ "<em>{}</em>".format(key), make_html(response['description']) ]
+            if 'headers' in fields:
+                header = ''
+                if 'headers' in response:
+                    hrow = []
+                    for header, h_obj in response['headers'].iteritems():
+                        hrow += "{} ({})".format(header, h_obj['type'])
+                        if 'description' in h_obj:
+                            hrow += ": {}".format(h_obj['description'])
+                    header = '  \n'.join(hrow)
+                row.append(header)
+            if 'schema' in fields:
+                schema = ''
+                if 'schema' in response:
+                    if '$ref' in response['schema']:
+                        schema += make_ref(response['schema']['$ref'])
+                    if 'type' in response['schema']:
+                        if response['schema']['type'] == 'array':
+                            if '$ref' in response['schema']['items']:
+                                schema += make_ref(response['schema']['items']['$ref'])
+                            schema = "[ {} ]".format(schema)
+                row.append(schema)
+            if 'examples' in fields:
+                if 'examples' in response:
+                    row.append(response['examples'])
+                else:
+                    row.append('')
+            table.append(row)
+        return make_table(table)
+    except KeyError as e:
+        handleException('KeyError', e)
+
+def make_paths(sections, json_data):
+    md = '<h2><a name="paths"></a>Paths</h2>\n'
+    for key in sorted(sections):
+        md += '<h3><a name="paths_{0}"></a>{0}</h3>\n'.format(key)
+        for section in sections[key]:
+            md += '<h4><a name="{}"></a><code>{}</code></h4>\n'.format(
+                section['href'], section['title']
+            )
+            operation = section['operation']
+            if 'summary' in operation:
+                md += '<p>Summary: {}</p>\n'.format(make_html(operation['summary']))
+            if 'description' in operation:
+                md += '<p>Description: {}</p>\n'.format(make_html(operation['description']))
+            md += '<h5>Parameters</h5>\n'
+            if 'parameters' in operation and len(operation['parameters']) > 0:
+                md += make_params_table(operation['parameters'], json_data)
+            else:
+                md += "<p><em>None</em></p>\n"
+            md += '<h5>Responses</h5>\n'
+            md += make_responses_table(operation['responses'])
+        md += '\n'
+    md += '\n'
+    return md
+
+def make_contents(path_section, json_data):
+    md = '<h3>Contents</h3>\n'
+    md += '<ul>\n'
+    md += '  <li><a href="#paths">Paths</a>\n'
+    md += '    <ul>\n'
+    for key in sorted(path_section):
+        md += '      <li><a href="#paths_{0}">{0}</a>\n'.format(key)
+        md += '        <ul>\n'
+        for section in path_section[key]:
+            md += '          <li><a href="#{}">{}</a></li>\n'.format(
+                section['href'], section['title']
+            )
+        md += '        </ul>\n'
+        md += '      </li>\n'
+    md += '    </ul>\n'
+    md += '  </li>\n'
+    md += '  <li><a href="#definitions">Models</a>\n'
+    md += '    <ul>\n'
+    for key in sorted(json_data['definitions']):
+        md += '      <li><a href="#definitions_{0}">{0}</a></li>\n'.format(key)
+    md += '    </ul>\n'
+    md += '  </li>\n'
+    md += '</ul>\n'
+    return md
+
+def make_definitions(json_data):
+    md = '<h2><a name="definitions"></a>Models</h2>\n'
+    for name in sorted(json_data['definitions']):
+        md += '<h3><a name="definitions_{0}"></a>{0}</h3>\n'.format(name)
+        model = json_data['definitions'][name]
+        if 'properties' in model:
+            fields = list(
+                set(['type']).union(
+                    *map(lambda x: x.keys(),
+                        map(lambda x: model['properties'][x], model['properties'].keys())
+                    )
+                )
+            )
+            row = [ 'Property', 'Type' ]
+            if 'description' in fields:
+                row.append('Description')
+            table = [ row ]
+            for key in sorted(model['properties']):
+                property = model['properties'][key]
+                row = [ "<em>{}</em>".format(key) ]
+                if 'type' in property:
+                    type = property['type']
+                    if 'format' in property:
+                        type += " ({})".format(property['format'])
+                    row.append("<em>{}</em>".format(type))
+                elif '$ref' in property:
+                    row.append(make_ref(property['$ref']))
+                else:
+                    row.append('')
+                if 'description' in fields:
+                    if 'description' in property:
+                        row.append(make_html(property['description']))
+                    else:
+                        row.append('')
+                table.append(row)
+        md += make_table(table)
+    return md
+
+def make_markdown(json_data):
+    path_sections = {}
+    for endpoint in json_data['paths']:
+        path_split = endpoint.split('/')
+        path_key = path_split[1]
+        if not path_key in path_sections:
+            path_sections[path_key] = []
+        for method, operation in json_data['paths'][endpoint].iteritems():
+            if 'operationId' in operation:
+                link = operation['operationId']
+            else:
+                link = ''.join([
+                    c for c in endpoint if c not in ['/', '{', '}']
+                ])
+            path_sections[path_key].append({
+                'title': '{} {}'.format(method.upper(), endpoint),
+                'href': 'paths_{}_{}'.format(link, method.upper()),
+                'operation': operation
+            })
+    md = make_header(json_data)
+    md += make_contents(path_sections, json_data)
+    md += make_paths(path_sections, json_data)
+    md += make_definitions(json_data)
+    return md
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('SPECFILE', help="path to swagger.json file")
+    parser.add_argument('OUTFILE', help="path to output HTML file")
+    args = parser.parse_args()
+
+    marked_down = make_markdown(get_json(args.SPECFILE))
+
+    if args.OUTFILE:
+        write_file(args.OUTFILE, marked_down)
+        print " success: {}".format(args.OUTFILE)
+    else:
+        print marked_down
+
+if __name__ == '__main__':
+    main()