软件使用
理解Redis的几种数据结构
工具软件 • zkbhj 发表了文章 • 0 个评论 • 2172 次浏览 • 2018-01-29 14:31
一、Redis数据库的优势
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exe
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"SDS的数据结构如下：
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储： a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101” 这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。#redis-cli.exe
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"节点的定义：
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义
typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：
链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"常用命令：sadd, srem, spop, sdiff, smembers, sunion等
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。 查看全部
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exe
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"SDS的数据结构如下：
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储： a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101” 这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。#redis-cli.exe
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"节点的定义：
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义
typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：
链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"常用命令：sadd, srem, spop, sdiff, smembers, sunion等
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。 查看全部
一、Redis数据库的优势
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储：
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exeSDS的数据结构如下：
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储：
a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。
b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101”这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。
#redis-cli.exe节点的定义：
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：- 链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。
- 因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。
- 通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe常用命令：sadd, srem, spop, sdiff, smembers, sunion等
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。
项目调研：Swagger - RESTFUL接口的文档在线自动生成功能测试框架
工具软件 • zkbhj 发表了文章 • 0 个评论 • 1854 次浏览 • 2018-01-17 12:03
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
有关该API的一般性描述可用路径（/资源）在每个路径上的可用操作（获取/提交...）每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
几乎所用支持OpenAPI规范的工具都支持YAML有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}这个文档的内容分成四部分，下面分别来说明。
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：schemes:
- https
host: simple.api
basePath: /openapi101这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.2.1 添加一个路径（path）
我们添加一个/persons的路径，用来访问一组用户信息：
paths:
/persons:2.2.2 在路径中添加一个HTTP方法
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3 定义请求参数（query parameters）
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3.1 在get方法中增加请求参数
首先我们在 get 方法中增加一个参数属性：
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################2.3.2 添加分页参数
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述： parameters:
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################2.4.1 添加一个 get /persons/{username} 操作
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################2.4.2 定义路径参数 username
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:
- name: username
in: path
required: true
description: The person's username
type: string定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
查看全部
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
有关该API的一般性描述可用路径（/资源）在每个路径上的可用操作（获取/提交...）每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
几乎所用支持OpenAPI规范的工具都支持YAML有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}这个文档的内容分成四部分，下面分别来说明。
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：schemes:
- https
host: simple.api
basePath: /openapi101这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.2.1 添加一个路径（path）
我们添加一个/persons的路径，用来访问一组用户信息：
paths:
/persons:2.2.2 在路径中添加一个HTTP方法
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3 定义请求参数（query parameters）
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3.1 在get方法中增加请求参数
首先我们在 get 方法中增加一个参数属性：
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################2.3.2 添加分页参数
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述： parameters:
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################2.4.1 添加一个 get /persons/{username} 操作
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################2.4.2 定义路径参数 username
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:
- name: username
in: path
required: true
description: The person's username
type: string定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
查看全部
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
我们添加一个/persons的路径，用来访问一组用户信息：
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
首先我们在 get 方法中增加一个参数属性：
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述：
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
- 有关该API的一般性描述
- 可用路径（/资源）
- 在每个路径上的可用操作（获取/提交...）
- 每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
- OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出
- 根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来
- 一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：swagger: "2.0"对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
- 几乎所用支持OpenAPI规范的工具都支持YAML
- 有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"这个文档的内容分成四部分，下面分别来说明。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：
schemes:这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
- https
host: simple.api
basePath: /openapi101
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"2.2.1 添加一个路径（path）
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
我们添加一个/persons的路径，用来访问一组用户信息：
paths:2.2.2 在路径中添加一个HTTP方法
/persons:
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：
responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:2.3 定义请求参数（query parameters）
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"2.3.1 在get方法中增加请求参数
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
首先我们在 get 方法中增加一个参数属性：
paths:2.3.2 添加分页参数
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述：
parameters:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"2.4.1 添加一个 get /persons/{username} 操作
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"2.4.2 定义路径参数 username
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
- name: username
in: path
required: true
description: The person's username
type: string
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
理解Redis的几种数据结构
工具软件 • zkbhj 发表了文章 • 0 个评论 • 2172 次浏览 • 2018-01-29 14:31
一、Redis数据库的优势
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exe
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"SDS的数据结构如下：
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储： a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101” 这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。#redis-cli.exe
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"节点的定义：
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义
typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：
链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"常用命令：sadd, srem, spop, sdiff, smembers, sunion等
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。 查看全部
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exe
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"SDS的数据结构如下：
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储： a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101” 这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。#redis-cli.exe
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"节点的定义：
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义
typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：
链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"常用命令：sadd, srem, spop, sdiff, smembers, sunion等
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。 查看全部
一、Redis数据库的优势
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储：
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。
Redis是一个先进的Key-Value键值存储数据库，通常作为数据结构服务器。
支持strings, hashes, lists, sets, sorted sets, bitmaps 和hyperloglogs
二、Redis数据结构
1、string - 字符串
Redis的字符串为SDS（Simple Dynamic String）可以存储任何东西，最大长度可达515兆。
#redis-cli.exeSDS的数据结构如下：
127.0.0.1:6379> set name 'cbb'
OK
127.0.0.1:6379> get name
"cbb"
struct sdshdr {
// 记录 buf 数组中已使用字节的数量
// 等于 SDS 所保存字符串的长度
int len;
// 记录 buf 数组中未使用字节的数量
int free;
// 字节数组，用于保存字符串
char buf[];
};常用命令：set, get2，Hash - 哈希值
Redis的哈希值是字符串字段和字符串值之间的映射，所有它们被用来表示对象。
#redis-cli.exe上面的Hash数据类型，用于存储用户的基本信息，user：1是键。
127.0.0.1:6379> HMSET user:1 username ccc password 123 age 20
OK
127.0.0.1:6379> HGETALL user:1 //取所有key
1> "username"
2> "ccc"
3> "passwrod"
4> "123"
5> "age"
6> "20"
127.0.0.1:6379> hget user:1 username //取一个key
"ccc"
hash解决了用户信息对象的存储：如用户ID为key，value为姓名name，年龄age，生日birthday等。
用普通的key/value结构存储：
a，set u001 “张三, 18, 20010101”
这种方式的缺点是增加了序列化/反序列化的开销，并且在需要修改其中一项信息时，需要把整个对象取回，并且修改操作需要对并发进行保护，引入CAS等复杂问题。
b，mset user:001:name “李三” user:001:age 18 user:001:birthday “20010101”这种方法是用户信息对象有多少个成员就存成多少个key-value对儿，虽然省去了序列化开销和并发问题，但是用户ID为重复存储，如果存在大量这样的数据，内存浪费严重。
常用命令：hmset, hset, hget, hgetall
3，List - 列表
列表是简单的字符串列表，排序插入顺序。可以添加元素到Redis列表的头部或尾部。
#redis-cli.exe节点的定义：
127.0.0.1:6379> lpush tutor redis
<integer> 1
127.0.0.1:6379> lpush tutor mongodb
<integer> 2
127.0.0.1:6379> lpush tutor rabitmq
<integer> 3
127.0.0.1:6379> lrange tutor 0 10
1> "rabitmq"
2> "mongodb"
3> "redis"
typedef struct listNode {
// 前置节点
struct listNode *prev;
// 后置节点
struct listNode *next;
// 节点的值
void *value;
} listNode;List的定义typedef struct list {
// 表头节点
listNode *head;
// 表尾节点
listNode *tail;
// 链表所包含的节点数量
unsigned long len;
// 节点值复制函数
void *(*dup)(void *ptr);
// 节点值释放函数
void (*free)(void *ptr);
// 节点值对比函数
int (*match)(void *ptr, void *key);
} list;补充：- 链表被广泛用于实现 Redis 的各种功能， 比如列表键， 发布与订阅， 慢查询， 监视器， 等等。
- 因为链表表头节点的前置节点和表尾节点的后置节点都指向 NULL ， 所以 Redis 的链表实现是无环链表。
- 通过为链表设置不同的类型特定函数， Redis 的链表可以用于保存各种不同类型的值。
常用命令：lpush, rpush, lpop, rpop, lrange等
4，Set - 集合
Set是字符串的无序集合。在Redis中可以添加、删除和测试值是否存在。
#redis-cli.exe常用命令：sadd, srem, spop, sdiff, smembers, sunion等
127.0.0.1:6379> sadd total 123
<integer> 1
127.0.0.1:6379> sadd total 234
<integer> 1
127.0.0.1:6379> sadd total 345
<integer> 1
127.0.0.1:6379> smembers total
1> "123"
2> "234"
3> "345"
5，Sort Set - 有序集合
与Set类似，字符串不重复，但其是有序的
常用命令：zadd， zrange，zrem，zcard等
6，Pub/Sub - 消息订阅
发布（Publish）和订阅（Subscribe）
~两客户端之间~
client1：
client2:
当一个key值上进行了消息发布后，所有订阅它的客户端都会收到相应的消息。
这一功能最明显的用法是作为实时消息系统，比如普通的即时聊天，群聊等功能。
项目调研：Swagger - RESTFUL接口的文档在线自动生成功能测试框架
工具软件 • zkbhj 发表了文章 • 0 个评论 • 1854 次浏览 • 2018-01-17 12:03
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
有关该API的一般性描述可用路径（/资源）在每个路径上的可用操作（获取/提交...）每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
几乎所用支持OpenAPI规范的工具都支持YAML有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}这个文档的内容分成四部分，下面分别来说明。
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：schemes:
- https
host: simple.api
basePath: /openapi101这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.2.1 添加一个路径（path）
我们添加一个/persons的路径，用来访问一组用户信息：
paths:
/persons:2.2.2 在路径中添加一个HTTP方法
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3 定义请求参数（query parameters）
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3.1 在get方法中增加请求参数
首先我们在 get 方法中增加一个参数属性：
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################2.3.2 添加分页参数
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述： parameters:
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################2.4.1 添加一个 get /persons/{username} 操作
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################2.4.2 定义路径参数 username
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:
- name: username
in: path
required: true
description: The person's username
type: string定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
查看全部
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
有关该API的一般性描述可用路径（/资源）在每个路径上的可用操作（获取/提交...）每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
几乎所用支持OpenAPI规范的工具都支持YAML有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}这个文档的内容分成四部分，下面分别来说明。
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：schemes:
- https
host: simple.api
basePath: /openapi101这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.2.1 添加一个路径（path）
我们添加一个/persons的路径，用来访问一组用户信息：
paths:
/persons:2.2.2 在路径中添加一个HTTP方法
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3 定义请求参数（query parameters）
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string2.3.1 在get方法中增加请求参数
首先我们在 get 方法中增加一个参数属性：
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################2.3.2 添加分页参数
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述： parameters:
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################2.4.1 添加一个 get /persons/{username} 操作
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################2.4.2 定义路径参数 username
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:
- name: username
in: path
required: true
description: The person's username
type: string定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
查看全部
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
我们添加一个/persons的路径，用来访问一组用户信息：
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
首先我们在 get 方法中增加一个参数属性：
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述：
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、基础介绍
1.1、什么是 Swagger?
The World's Most Popular Framework for APIs.
Starting January 1st 2016 the Swagger Specification has been donated（捐赠） to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification.
Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在 github。
1.2 OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
- 有关该API的一般性描述
- 可用路径（/资源）
- 在每个路径上的可用操作（获取/提交...）
- 每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。关于规范的学习和理解，本文最后还有个彩蛋。
1.3 为啥要使用OpenAPI规范？
- OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出
- 根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来
- 一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册...
1.4 如何编写API文档？
1.4.1 语言：JSON vs YAML
我们可以选择使用JSON或者YAML的语言格式来编写API文档。但是个人建议使用YAML来写，原因是它更简单。一图胜千言，先看用JSON写的文档：
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Simple API",
"description": "A simple API to learn how to write OpenAPI Specification"
},
"schemes": [
"https"
],
"host": "simple.api",
"basePath": "/openapi101",
"paths": {
"/persons": {
"get": {
"summary": "Gets some persons",
"description": "Returns a list containing all persons.",
"responses": {
"200": {
"description": "A list of Person",
"schema": {
"type": "array",
"items": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"username": {
"type": "string"
}
}
}
}
}
}
}
}
}
}再来看看同一份API文档的YAML实现：swagger: "2.0"对于普通人来说，似乎用YAML更能够简化书写和阅读。这里我们并没有非此即彼的选择问题，因为：
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
- 几乎所用支持OpenAPI规范的工具都支持YAML
- 有很多的工具可以实现YAML-JSON之间的转换
所以，用自己喜欢的方式书写即可。（后面的示例文档也都是用YAML来写的。强烈推荐使用YAML。）
1.4.2 编辑器
编写API文档，其实我们只是在写一个简单的文本文件。我们可以用任何最普通的文档编辑器来写。但是为了提高效率，还是建议使用专业的编辑工具。众多工具中，最好的选择是Swagger Editor，它能够提供语法高亮、自动完成、即时预览等功能，非常强大。左边编辑API文档，右边实时预览。下面这张动图展示编辑功能。
我们可以使用在线版本来编辑，也可以非常简单的本地部署，更多细节请参考另一篇文档开源仓库上的说明。
二、从零开始
这一章主要介绍API的基本组成部分，包括提供给API消费者（所有可能访问API的个体，下简称“消费者”）的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。
2.1 最简单的例子
我们从一个最简单（几乎没有东西）的API文档开始：
swagger: "2.0"这个文档的内容分成四部分，下面分别来说明。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}
2.1.1 OpenAPI规范的版本号
首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"你没看错，是swagger，上面已经介绍了，OpenAPI规范是基于Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为2.0。
2.1.2 API描述信息
然后我们需要说明一下API文档的相关信息，比如API文档版本（注意不同于上面的规范版本）、API文档名称已经可选的描述信息。
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
2.1.3 API的URL
作为web API，一个很重要的信息就是用来给消费者使用的根URL，可以用协议（http或者https）、主机名、根路径来描述：
schemes:这这个例子中，消费者把https//simple.api/open101作为根节点来访问各种API。因为和具体环境有关，不涉及API描述的根本内容，所以这部分信息是可选的。
- https
host: simple.api
basePath: /openapi101
2.1.4 API的操作（operation）
这个例子中，我们没有写API的操作，用一个YAML的空对象{}先占个位置。
2.2 定义一个API操作
如果我们要展示一组用户信息，可以这样描述：
swagger: "2.0"2.2.1 添加一个路径（path）
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
我们添加一个/persons的路径，用来访问一组用户信息：
paths:2.2.2 在路径中添加一个HTTP方法
/persons:
在每个路径中，我们可以添加任意的HTTP动词来操作所需要的资源。
比如需要展示一组用户信息，我们可以在/persons路径中添加get方法，同时还可以填写一些简单的描述信息（summary）或者说明该方法的一段长篇大论（description）。
get:
summary: Gets some persons
description: Returns a list containing all persons.
这样一来，我们调 get https//simple.api/open101/persons方法就能获取一个用户信息列表了。
2.2.3 定义响应（response）类型
对于每个方法（或操作），我们都可以在响应(responses)中添加任意的HTTP状态码（比如200 OK 或者 404 Not Found等）。这个例子中我们添加上200的响应：
responses:
200:
description: A list of Person
2.2.4 定义响应内容
get /persons这个接口返回一组用户信息，我们通过响应消息中的模式（schema）属性来描述清楚具体的返回内容。
一组用户信息就是一个用户信息对象的数组（array），每一个数组元素则是一个用户信息对象（object），该对象包含三个string类型的属性：姓氏、名字、用户名，其中用户名必须提供（required）。
schema:2.3 定义请求参数（query parameters）
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。
swagger: "2.0"2.3.1 在get方法中增加请求参数
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ############################################################################
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
首先我们在 get 方法中增加一个参数属性：
paths:2.3.2 添加分页参数
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
#START############################################################################
parameters:
# END ############################################################################
在参数列表中，我们添加两个名字（name）分别叫做pageSize和pageNumber的整型（integer）参数，并作简单描述：
parameters:这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
#START############################################################################
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
# END ##############################################################################
responses:
2.4 定义路径参数（path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。
swagger: "2.0"2.4.1 添加一个 get /persons/{username} 操作
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
# END ############################################################################
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
swagger: "2.0"2.4.2 定义路径参数 username
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
****
username:
type: string
#START############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username
# END ############################################################################
因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ） 里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。
parameters:定义路径参数时很容易出现的问题就是忘记：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也就是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
- name: username
in: path
required: true
description: The person's username
type: string
2.4.3 定义响应消息
别忘了获取单个用户信息也需要填写 200 响应消息，响应消息体的内容就是之前描述过的用户信息（用户信息列表中的一个元素）：
responses:当然，API的提供者会对 username 进行校验，如果查无此人，应该返回 404 的异常状态。所以我们再加上 404 状态的响应：
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
2.5 定义消息体参数（body parameter）
当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。
swagger: "2.0"
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Gets some persons
description: Returns a list containing all persons. The list supports paging.
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
#START############################################################################
post:
summary: Creates a person
description: Adds a new person to the persons list.
parameters:
- name: person
in: body
description: The person to create.
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
responses:
204:
description: Persons succesfully created.
400:
description: Persons couldn't have been created.
# END ############################################################################
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.