Swagger 主体惯例

Swagger是Web API描述文档的规范。通常采用JSON或者YAML格式，此处我们统一采用JSON格式。

Load 或者 Index

• Load 是根据ID获取某个资源的详情。
• Index 是根据某种条件，获取资源的列表。

响应体

响应体按照以下固定的写法，只需要将 Action 和 Resource 根据实际情况进行替换即可。 响应体的定义继承了 ResponseBodyCommonProperties ，同时将 collection 定义成数组，并将元素的类型指向 {Action}{Resource}ResponseItem。

• Action 的取值只能是Load或者Index。
• Resource 只能是资源的英文单词的单数形式。

  "{Action}{Resource}ResponseBody": {
    "description": "{Action}{Resource}的响应体",
    "allOf": [
      { "$ref": "#/definitions/ResponseBodyCommonProperties" },
      { "type": "object", "properties": { "collection": { "type": "array", "items": { "$ref": "#/definitions/{Action}{Resource}ResponseItem" } } } }
    ]
  }
  

响应项

响应项定义单个资源的数据结构。其中 links 属性是要求的标准属性，其名称、类型都必须如下定义。 对于一些常用的领域类型，如移动电话号码，可以定义成常用的类型，在此直接引用。

  "{Action}{Resource}ResponseItem": {
    "type": "object",
    "properties": {
      "{Field_1}":           { "type": "string"                          },
      "{Field_2}":           { "type": "string"                          },
      "mobile_phone_number": { "$ref": "#/definitions/MobilePhoneNumber" },
      "links":               { "$ref": "#/definitions/LinkList"          }
    }
  }

Create、Update 或者 Destroy

• Create 是创建某个资源。
• Update 是根据ID更新某个资源。
• Destroy 是根据ID，销毁某个资源。

请求体

HTTP GET方法请求没有请求体，只有POST、PUT、PATCH、DELETE等方法才有请求体。

  "{Action}{Resource}RequestBody": {
    "description": "{Action}{Resource}的请求体",
    "type":        "object",
    "properties":  {
      "{Field_1}": { "type": "string" },
      "{Field_2}": { "type": "string" }
    }
  }

响应体

与前文响应体一致。

响应项

与前文响应项一致。