REST（英文：Representational State Transfer，又称具象状态传输）是Roy Thomas Fielding博士于2000年在他的博士论文 中提出来的一种万维网软件架构风格，目的是便于不同软件/程序在网络（例如互联网）中互相传递信息。

REST 的核心是可编辑的资源及其集合，用符合 Atom 文档标准的 Feed 和 Entry 表示。每个资源或者集合有一个惟一的 URI。系统以资源为中心，构建并提供一系列的 Web 服务。

在 REST 中，开发人员显式地使用 HTTP 方法，对系统资源进行创建、读取、更新和删除的操作：

• 使用 POST 方法在服务器上创建资源
• 使用 GET 方法从服务器检索某个资源或者资源集合
• 使用 PUT 方法对服务器的现有资源进行更新
• 使用 DELETE 方法删除服务器的某个资源

如果一个架构符合REST原则，就可以称它为。

RESTful API 设计定义

以下是几个RESTful API的几个概念。

• 资源（Resource）：系统上的所有事物都被抽象为资源（一篇文章，一张照片，一段语音）
• 集合（Collection）：一组资源的合辑称为集合（几篇文章，几张照片）
• 路径（Endpoint）：路径又称”终点“，表示API的具体网址（每个网址代表一种资源）

那么一个设计良好的RESTful API应该遵循哪些原则呢？

协议

API与用户的通信协议总是使用HTTPs协议。

域名

应该尽量将API部署在专用域名，例如：

API地址和版本

在url中指定API版本。比如：

以资源为中心设计URL

使用正确的Method

• GET：从服务器取出资源
• POST：在服务器新建一个资源
• PUT：在服务器更新资源（客户端提供改变后的完整资源
• PATCH：在服务器更新资源（客户端只提供改变了属性）
• DELETE：从服务器删除资源

还是使用 github 的例子：

正确的过滤信息（filtering）

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

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

• ?limit=10: 指定返回记录的数量
• ?offset=10：指定返回记录的开始位置
• ?page=2&per_page=100：：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?animal_type_id=1：指定筛选条件

选择合适的状态码

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

常见的状态码有以下几种：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）

错误处理（Error handling）

如果出错的话，在response body 中通过 message 给出明确的信息。如果状态码是4xx，就应该向用户返回出错信息。

良好的文档

文档应该是规范的API的重要的组成部分，没有文档的API是难以给他人使用的，也是不利于维护的。

其它

• 使用 OAuth2.0 鉴权
• 尽量使用JSON作为返回的数据格式
• 限流

对应上述规则，我们并不能保证其它的API提供者也会遵守，特别是文档，有很大一部分API提供者给出的文档是pdf或者word文档，这是因为在API的迭代开发过程中，文档更新会比较麻烦。

swagger帮API使用者和开发者纠正了这个问题。

Swagger是一个简单但功能强大的API表达工具。改框架为创建JSON或YAML格式的RESTful API 文档提供了OpenAPI规范。swagger文档可由各种编程语言处理，可以在软件开发周期中嵌入源代码控制系统中，以便进行版本管理。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

我们可以选择使用JSON或者YAML来编写API文档。文档示例如下：

json 格式文档：

yaml 格式文档：

可以发现，yaml格式的文档比json格式的更清晰，可读性更高，推荐使用yaml格式书写文档。

swagger 官网提供了 swagger editor: http://editor.swagger.io/#/，你可以在这个编辑器中创建或导入文档，并在交互式环境中浏览它。

以下是您导入 leads.yaml 定义后的 Swagger Editor UI 外观：

右侧的显示窗格显示了格式化的文档，反映了在左侧窗格中的代码编辑器中执行的更改。代码编辑器会指出了所有格式错误。你可以展开和折叠每个窗格。

我用一个例子来介绍下swagger文档的基本结构，这里我用yaml格式来编写文档：

上述文档包括数据（Metadata）、Base URL、API路径（paths）三部分：

Metadata

这部分信息包括swagger 使用的版本：

API相关的描述信息（比如API介绍、版本等）：

Base URL

作为web API，一个很重要的信息就是用来给用户使用的 根URL，可用协议（http/https）、host地址：

所有的API都是base URL 的相对路径 例如 /users 的API地址是 。

路径（Paths）

paths 部分定义API的路径（endpoint）、支持的HTTP 请求方法

当然，写完文档并不代表我们的代码就可以直接使用这份文档以及文档中的约束，swagger 还提供了 swagger-codegen：https://github.com/swagger-api/swagger-codegen。

swagger-codegen 是一个开源的代码生成工具，它包含一个模板驱动引擎，可以直接从我们定义的 swagger 文档中生成可视化的文档查看界面和API客户端。

这是一个开源的项目，地址是swagger-codegens： https://github.com/swagger-api/swagger-codegen。可以自己安装使用一下。

因为我最常用的语言是Python，所以给大家介绍一个第三方的 python 的代码生成器swagger-py-codegen：https://github.com/guokr/swagger-py-codegen

swagger-py-codegen的亮点是它是一个Python web framework 代码生成器，可以根据swagger 文档自动生成相应web framework 的代码，现在支持 Flask, Tornado，falcon，最新版将支持sanic。

可以使用 pip 安装：

安装后使用命令如下：

可选参数有：

举个例子

我们这里使用 swagger-py-codegen 提供的测试文档 执行：

生成的代码目录结构如下

可以看到，这时一个简单的app框架已经生成了，其中 routes.py 是自动生成的路由，validators.py 是response和request的校验代码，schemas.py 是由文档生成的校验规则，api 目录下的各个文件是你定义的endpoint。

这时运行demo 目录下的 文件:

会发现 server 已经启动：

如果生成命令带上 --ui --spec，生成代码的同时也会生成swagger UI：

启动server后在浏览器输入地址

可以看到直接使用的 swagger UI。

swagger-py-codegen 认证默认使用 OAuth2 认证方式，认证部分代码需要自己实现。

现在代码结构已经生成，可以安心的写逻辑代码了。

• REST
• RESTful API 设计指南
• Principles of good RESTful API Design
• 跟着 Github 学习 Restful HTTP API 设计
• 最佳实践：更好的设计你的 REST API
• swagger
• 如何编写基于OpenAPI规范的API文档
• 使用 Swagger 文档化和定义 RESTful API
• swagger 文档
• swagger-py-codegen

---

最后，感谢女朋友支持。

今天的文章 swagger地址是什么（swagger文档地址）分享到此就结束了，感谢您的阅读。