Merge pull request OAI#372 from swagger-api/guidelines

Guidelines

Author: webron

guidelines/sample-server/files/models.json

@@ -1,5 +1,6 @@
 {
   "Model": {
+    "type": "object",
     "description": "A simple model",
     "properties": {
       "id": {
@@ -13,6 +14,7 @@
     }
   },
   "Tag": {
+    "type": "object",
     "description": "A tag entity in the system",
     "properties": {
       "name": {
@@ -21,6 +23,7 @@
     }
   },
   "Health": {
+    "type": "object",
     "description": "An object representing the health of a server",
     "required": [
       "liveThreadCount",
@@ -52,6 +55,7 @@
     }
   },
   "JVMMemory": {
+    "type": "object",
     "required": [
       "allocated",
       "max",
@@ -81,5 +85,24 @@
         "format": "double"
       }
     }
+  },
+  "ErrorMessage": {
+    "type": "object",
+    "description": "A shared model for error message",
+    "required" : ["errorCode","reason"],
+    "properties": {
+      "errorCode": {
+        "type": "integer",
+        "format": "int64"
+      },
+      "reason": {
+        "description": "the reason for this error",
+        "type": "string"
+      },
+      "description": {
+        "description": "an optional longer description of this error message",
+        "type": "string"
+      }
+    }
   }
 }

guidelines/sample-server/files/operations.json

@@ -16,8 +16,12 @@
           "schema": {
             "$ref": "http://localhost:8000/models.json#/Health"
           }
+        },
+        "404": {
+          "$ref": "http://localhost:8000/responses.json#/NotFoundError"
         }
       }
     }
   }
 }
+

guidelines/sample-server/files/responses.json

@@ -0,0 +1,8 @@
+{
+  "NotFoundError": {
+    "description": "Entity not found",
+    "schema": {
+      "$ref": "http://localhost:8000/models.json#/ErrorMessage"
+    }
+  }
+}

guidelines/sample-server/files/swagger.json

@@ -36,6 +36,9 @@
                 "$ref": "http://localhost:8000/models.json#/Health"
               }
             }
+          },
+          "404": {
+            "$ref": "http://localhost:8000/responses.json#/NotFoundError"
           }
         }
       }