Swagger 路径惯例

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

在 Swagger 文档里的 paths 部分，定义了Web API的路径。

URL的路径部分，采用以下两种形式：

• /{resources}
  • GET请求 根据参数返回列表。
  • POST请求 根据请求体内的数据创建资源。
• /{resources}/{id}
  • GET请求 根据ID返回单个资源或404。
  • PUT请求或PATCH请求 根据ID找到单个资源，并将这个资源更新为请求体中的数据。
  • DELETE请求 根据ID找到单个资源，并将这个资源进行销毁。

检索资源列表

根据参数返回列表。

  "/{resources}": {
    "get": {
      "summary":     "...",
      "description": "...",
      "tags":        [ "{resource}" ],
      "parameters":  [
        {
          "name":        "page",
          "in":          "query",
          "description": "...",
          "required":    true,
          "schema":      { "$ref": "#/definitions/{Page}" }
        }
      ],
      "responses": {
        "200": {
          "description": "...",
          "schema":      { "$ref": "#/definitions/Index{Resource}ResponseBody" }
        },
        "default": {
          "description": "出现错误。",
          "schema":      { "$ref": "#/definitions/ErrorResponseBody" }
        }
      }
    }
  }

加载资源详情

根据ID返回单个资源或404。

  "/{resources}/{id}": {
    "get": {
      "summary":     "...",
      "description": "...",
      "tags":        [ "{resource}" ],
      "parameters":  [
        {
          "name":        "id",
          "in":          "path",
          "description": "...",
          "required":    true,
          "schema":      { "$ref": "#/definitions/{ResourceId}" }
        }
      ],
      "responses": {
        "200": {
          "description": "...",
          "schema":      { "$ref": "#/definitions/Load{Resource}ResponseBody" }
        },
        "default": {
          "description": "出现错误。",
          "schema":      { "$ref": "#/definitions/ErrorResponseBody" }
        }
      }
    }
  }

创建资源

根据请求体内的数据创建资源。

  "/{resources}": {
    "post": {
      "summary":     "...",
      "description": "...",
      "tags":        [ "{resource}" ],
      "parameters":  [
        {
          "name":        "request_body",
          "in":          "body",
          "description": "JSON格式的请求体。解释所有的字段。",
          "required":    true,
          "schema":      { "$ref": "#/definitions/Create{Resource}RequestBody" }
        }
      ],
      "responses": {
        "201": {
          "description": "成功的返回。",
          "schema":      { "$ref": "#/definitions/Create{Resource}ResponseBody" }
        },
        "default": {
          "description": "出现错误。",
          "schema":      { "$ref": "#/definitions/ErrorResponseBody" }
        }
      }
    }
  }

更新资源

根据ID找到单个资源，并将这个资源更新为请求体中的数据。

  "/{resources}/{id}": {
    "put": {
      "summary":     "...",
      "description": "...",
      "tags":        [ "{resource}" ],
      "parameters":  [
        {
          "name":        "id",
          "in":          "path",
          "description": "{Resource}的ID。",
          "required":    true,
          "schema":      { "$ref": "#/definitions/{ResourceId}" }
        },
        {
          "name":        "request_body",
          "in":          "body",
          "description": "JSON格式的请求体。解释所有的字段。",
          "required":    true,
          "schema":      { "$ref": "#/definitions/Update{Resource}RequestBody" }
        }
      ],
      "responses": {
        "200": {
          "description": "成功的返回。",
          "schema":      { "$ref": "#/definitions/Update{Resource}ResponseBody" }
        },
        "default": {
          "description": "出现错误。",
          "schema":      { "$ref": "#/definitions/ErrorResponseBody" }
        }
      }
    }
  }

销毁资源

根据ID找到单个资源，并将这个资源进行销毁。

  "/{resources}/{id}": {
    "delete": {
      "summary":     "...",
      "description": "...",
      "tags":        [ "{resource}" ],
      "parameters":  [
        {
          "name":        "id",
          "in":          "path",
          "description": "{Resource}的ID。",
          "required":    true,
          "schema":      { "$ref": "#/definitions/{ResourceId}" }
        },
        {
          "name":        "request_body",
          "in":          "body",
          "description": "JSON格式的请求体。解释所有的字段。",
          "required":    true,
          "schema":      { "$ref": "#/definitions/Destroy{Resource}RequestBody" }
        }
      ],
      "responses": {
        "200": {
          "description": "成功的返回。",
          "schema":      { "$ref": "#/definitions/Destroy{Resource}ResponseBody" }
        },
        "default": {
          "description": "出现错误。",
          "schema":      { "$ref": "#/definitions/ErrorResponseBody" }
        }
      }
    }
  }