Swagger

什么是 RESTful 什么是REST REST（英文：Representational State Transfer，又称具象状态传输）是Roy Thomas Fielding博士于2000年在他的博士论文[1] 中提出来的一种万维网软件架构风格，目的是便于不同软件/程序在网络（例如互联网）中互相传递信息。 REST 的核心是可编辑的资源及其集合，用符合 Atom 文档标准的 Feed 和 Entry 表示。每个资源或者集合有一个惟一的 URI。系统以资源为中心，构建并提供一系列的 Web 服务。 在 REST 中，开发人员显式地使用 HTTP 方法，对系统资源进行创建、读取、更新和删除的操作： 使用 POST 方法在服务器上创建资源 使用 GET 方法从服务器检索某个资源或者资源集合 使用 PUT 方法对服务器的现有资源进行更新 使用 DELETE 方法删除服务器的某个资源 如果一个架构符合REST原则，就可以称它为RESTful架构。 RESTful API 设计定义 以下是几个RESTful API的几个概念。 资源（Resource）：系统上的所有事物都被抽象为资源（一篇文章，一张照片，一段语音） 集合（Collection）：一组资源的合辑称为集合（几篇文章，几张照片） 路径（Endpoint）：路径又称”终点“，表示API的具体网址（每个网址代表一种资源） 那么一个设计良好的RESTful API应该遵循哪些原则呢？ 协议 API与用户的通信协议总是使用HTTPs协议。 域名 应该尽量将API部署在专用域名，例如： https://apis.gusibi.com API地址和版本 在url中指定API版本。比如： https://apis.gusibi.com/v1 以资源为中心设计URL 资源是RESTful API的核心元素，所有的操作都是针对特定资源进化的。而资源就是URL表示的，所以简洁、清晰、结构化的URL设计是至关重要的。 在RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。我们来看一下 Github 的例子： /users/:username/repos /users/:org/repos /repos/:owner/:repo /repos/:owner/:repo/tags /repos/:owner/:repo/branches/:branch 使用正确的Method 对于资源的具体操作类型，使用HTTP method 表示。 以下是常用的HTTP方法。 ...