使用 swagger 生成Flask RESTful API

什么是 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方法。

• GET：从服务器取出资源

• POST：在服务器新建一个资源

• PUT：在服务器更新资源（客户端提供改变后的完整资源

• PATCH：在服务器更新资源（客户端只提供改变了属性）

• DELETE：从服务器删除资源

还是使用 github 的例子：

GET /repos/:owner/:repo/issues
GET /repos/:owner/:repo/issues/:number
POST /repos/:owner/:repo/issues
PATCH /repos/:owner/:repo/issues/:number
DELETE /repos/:owner/:repo

正确的过滤信息（filtering）

如果记录数量很多，服务器不能都将他们返回给用户。API应该提供参数，过滤返回结果。

下边是一些是、常见的参数。

• ?limit=10: 指定返回记录的数量

• ?offset=10：指定返回记录的开始位置

• ?page=2&per_page=100：：指定第几页，以及每页的记录数。

• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

• ?animal_type_id=1：指定筛选条件

选择合适的状态码

HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

2XX：请求正常处理并返回3XX：重定向，请求的资源位置发生变化4XX：客户端发送的请求有错误5XX&#x