Swagger 通用定义

Swagger是Web API描述文档的规范。通常采用JSON或者YAML格式，此处我们统一采用JSON格式。 在Swagger文档的definitions部分中，需要先按照Dosser的规范，定义一些复用性很强的公共组件，以便在后续的工作中直接引用。

LinkList 链接列表

用于响应体的collection数组的每个资源的links字段。

  "LinkList": { "type":  "array", "items": { "type": "object", "properties": { "rel":  { "type": "string" }, "href": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" } } } }

ResponseBodyCommonProperties 响应体公共属性

根据Dosser的规范，success、code、message、size、errors、meta这6个属性的数据类型完全一致，因此可用以下的结构统一描述。 响应体公共属性的定义，是为了方便后续的引用和继承。

  "ResponseBodyCommonProperties": {
    "type": "object",
    "properties": {

      "success": { "type": "boolean"                    },
      "code":    { "type": "string"                     },
      "message": { "type": "string"                     },
      "size":    { "type": "integer", "format": "int32" },
      "errors":  { "type": "object",  "properties": { "type":  "array", "items": { "type": "string" } } },

      "meta": {
        "type": "object",
        "properties": {
          "timestamp":  { "type": "integer", "format":               "int32"              },
          "request_id": { "type": "string",  "format":               "uuid"               },
          "criteria":   { "type": "object",  "additionalProperties": { "type": "string" } }
        }
      }

    }
  }

ErrorResponseBody 错误响应体

错误响应体是基于 ResponseBodyCommonProperties ，融合 Dosser 规范定义的collection。

  "ErrorResponseBody": {
    "description": "出现错误时的响应体",
    "allOf": [
      { "$ref": "#/definitions/ResponseBodyCommonProperties" },
      { "type": "object", "properties": { "collection": { "type": "array", "items": { "type": "object",  "additionalProperties": { "type": "string" } } } } }
    ]
  }