通知设置 新通知
PHPStorm上传文件时提示invalid descendent file name "\"，怎么解决？
回复zkbhj 回复了问题 • 1 人关注 • 1 个回复 • 59 次浏览 • 2019-06-05 17:53
给小米手机线刷新系统时，出现‘err:'MySQL' 不是内部或外部命令’问题怎么解决？
回复zkbhj 回复了问题 • 1 人关注 • 1 个回复 • 253 次浏览 • 2018-12-13 16:22
新一代开源配置中心：Apollo
zkbhj 发表了文章 • 0 个评论 • 446 次浏览 • 2018-05-17 17:59
Apollo（Github主页）是携程框架部门研发的配置管理平台，能够集中化管理应用不同环境、不同集群的配置，配置修改后能够实时推送到应用端，并且具备规范的权限、流程治理等特性。
服务端基于Spring Boot和Spring Cloud开发，打包后可以直接运行，不需要额外安装Tomcat等应用容器。
Java客户端不依赖任何框架，能够运行于所有Java运行时环境，同时对Spring/Spring Boot环境也有额外支持。
.Net客户端不依赖任何框架，能够运行于所有.Net运行时环境。
更多参阅：https://yq.aliyun.com/articles/74601 查看全部
服务端基于Spring Boot和Spring Cloud开发，打包后可以直接运行，不需要额外安装Tomcat等应用容器。
Java客户端不依赖任何框架，能够运行于所有Java运行时环境，同时对Spring/Spring Boot环境也有额外支持。
.Net客户端不依赖任何框架，能够运行于所有.Net运行时环境。
更多参阅：https://yq.aliyun.com/articles/74601 查看全部
Apollo（Github主页）是携程框架部门研发的配置管理平台，能够集中化管理应用不同环境、不同集群的配置，配置修改后能够实时推送到应用端，并且具备规范的权限、流程治理等特性。
服务端基于Spring Boot和Spring Cloud开发，打包后可以直接运行，不需要额外安装Tomcat等应用容器。
Java客户端不依赖任何框架，能够运行于所有Java运行时环境，同时对Spring/Spring Boot环境也有额外支持。
.Net客户端不依赖任何框架，能够运行于所有.Net运行时环境。
更多参阅：https://yq.aliyun.com/articles/74601
理解Redis的几种数据结构
zkbhj 发表了文章 • 0 个评论 • 405 次浏览 • 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在PHP项目中的使用实践
zkbhj 发表了文章 • 0 个评论 • 504 次浏览 • 2018-01-17 12:17
上一篇文章我们一起学习了什么是swagger以及如何用官方提供的标准规范和语言（Json或者YAML）来生成我们的接口文档。但是我们部门的项目都是PHP开发的，要接入这个swagger，应该怎么做呢？今天这篇文章就是来做这个实践！
上一篇说的那么官方的介绍，但是这个swagger到底是个什么鬼呢？其实，说白了理解起来也很简单：
其实就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件（或者YAML）, 再通关Swagger前端来美化,整理JSON数据.
所以，看到这里，我们就知道了。要使用Swagger需要安装2个东西：
前端,用来显示;后端, 用来生成JSON
1, 安装前端
swagger-ui下载
git clone https://github.com/swagger-api/swagger-ui.git下载之后找到dist目录, 打开index.html把其中的那一串url改成自己的, 比如 http//localhost/yii2/swagger-docs/swagger.json
$(function () {
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost/yii2/swagger- ... 3B%3B
}还可以把界面调整成中文, 放开js文件的注释即可
<script src='lang/translator.js' type='text/javascript'></script>
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<script src='lang/zh-cn.js' type='text/javascript'></script>然后打开URL就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用, 直接访问前端就好
http://localhost/yii2/swagger-ui/dist/index.html2, 安装后端
git clone https://github.com/zircote/swagger-php.git因为公司用的是yii2, 所以使用了composer来安装
"require": { "zircote/swagger-php": "*" }之后composer update, 或者直接命令行, 详见官方安装指南。
DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php把swagger-php放在根目录下，然后用官方提供的Examples来生成测试json
cd swagger-php
mkdir doc
php swagger.phar Examples -o doc"-o" 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. "-o" 后面是生成到哪个path。我没有进入到swagger-php下面, 直接打的命令行, 任意路径下都可以执行生成json操作
php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs
然后再看http//localhost/yii2/swagger-ui/dist/index.html, 生成了API文档。
准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 官方参考文档
比如Model：
/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
* @SWG\Property(name="hostname", type="string"),
* @SWG\Property(name="label", type="string"),
* @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
// ...
}
比如Controller：
/**
* @SWG\Resource(
* basePath="http://skyapi.dev",
* resourcePath="/vps",
* @SWG\Api(
* path="/vps",
* @SWG\Operation(
* method="GET",
* type="array",
* summary="Fetch vps lists",
* nickname="vps/index",
* @SWG\Parameter(
* name="expand",
* description="Models to expand",
* paramType="query",
* type="string",
* defaultValue="vps,os_template"
* )
* )
* )
* )
*/
class VpsController extends Controller
{
// ...
}每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller, 先生成json再跳转到ui页面。
$b2broot = Yii::getAlias('@b2broot');
$swagger = \Swagger\scan($b2broot.'/myapi');
$json_file = $b2broot.'/swagger-docs/swagger.json';
$is_write = file_put_contents($json_file, $swagger);
if ($is_write == true) {
$this->redirect('http//localhost/yii2/swagger-ui/dist/index.html');
}参考文档：
https://www.cnblogs.com/handongyu/p/6992367.html
查看全部
上一篇说的那么官方的介绍，但是这个swagger到底是个什么鬼呢？其实，说白了理解起来也很简单：
其实就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件（或者YAML）, 再通关Swagger前端来美化,整理JSON数据.
所以，看到这里，我们就知道了。要使用Swagger需要安装2个东西：
前端,用来显示;后端, 用来生成JSON
1, 安装前端
swagger-ui下载
git clone https://github.com/swagger-api/swagger-ui.git下载之后找到dist目录, 打开index.html把其中的那一串url改成自己的, 比如 http//localhost/yii2/swagger-docs/swagger.json
$(function () {
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost/yii2/swagger- ... 3B%3B
}还可以把界面调整成中文, 放开js文件的注释即可
<script src='lang/translator.js' type='text/javascript'></script>
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<script src='lang/zh-cn.js' type='text/javascript'></script>然后打开URL就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用, 直接访问前端就好
http://localhost/yii2/swagger-ui/dist/index.html2, 安装后端
git clone https://github.com/zircote/swagger-php.git因为公司用的是yii2, 所以使用了composer来安装
"require": { "zircote/swagger-php": "*" }之后composer update, 或者直接命令行, 详见官方安装指南。
DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php把swagger-php放在根目录下，然后用官方提供的Examples来生成测试json
cd swagger-php
mkdir doc
php swagger.phar Examples -o doc"-o" 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. "-o" 后面是生成到哪个path。我没有进入到swagger-php下面, 直接打的命令行, 任意路径下都可以执行生成json操作
php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs
然后再看http//localhost/yii2/swagger-ui/dist/index.html, 生成了API文档。
准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 官方参考文档
比如Model：
/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
* @SWG\Property(name="hostname", type="string"),
* @SWG\Property(name="label", type="string"),
* @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
// ...
}
比如Controller：
/**
* @SWG\Resource(
* basePath="http://skyapi.dev",
* resourcePath="/vps",
* @SWG\Api(
* path="/vps",
* @SWG\Operation(
* method="GET",
* type="array",
* summary="Fetch vps lists",
* nickname="vps/index",
* @SWG\Parameter(
* name="expand",
* description="Models to expand",
* paramType="query",
* type="string",
* defaultValue="vps,os_template"
* )
* )
* )
* )
*/
class VpsController extends Controller
{
// ...
}每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller, 先生成json再跳转到ui页面。
$b2broot = Yii::getAlias('@b2broot');
$swagger = \Swagger\scan($b2broot.'/myapi');
$json_file = $b2broot.'/swagger-docs/swagger.json';
$is_write = file_put_contents($json_file, $swagger);
if ($is_write == true) {
$this->redirect('http//localhost/yii2/swagger-ui/dist/index.html');
}参考文档：
https://www.cnblogs.com/handongyu/p/6992367.html
查看全部
上一篇文章我们一起学习了什么是swagger以及如何用官方提供的标准规范和语言（Json或者YAML）来生成我们的接口文档。但是我们部门的项目都是PHP开发的，要接入这个swagger，应该怎么做呢？今天这篇文章就是来做这个实践！
上一篇说的那么官方的介绍，但是这个swagger到底是个什么鬼呢？其实，说白了理解起来也很简单：
所以，看到这里，我们就知道了。要使用Swagger需要安装2个东西：
1, 安装前端
swagger-ui下载
准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 官方参考文档
比如Model：
比如Controller：
https://www.cnblogs.com/handongyu/p/6992367.html
上一篇说的那么官方的介绍，但是这个swagger到底是个什么鬼呢？其实，说白了理解起来也很简单：
其实就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件（或者YAML）, 再通关Swagger前端来美化,整理JSON数据.
所以，看到这里，我们就知道了。要使用Swagger需要安装2个东西：
- 前端,用来显示;
- 后端, 用来生成JSON
1, 安装前端
swagger-ui下载
git clone https://github.com/swagger-api/swagger-ui.git下载之后找到dist目录, 打开index.html把其中的那一串url改成自己的, 比如 http//localhost/yii2/swagger-docs/swagger.json
$(function () {
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost/yii2/swagger- ... 3B%3B
}还可以把界面调整成中文, 放开js文件的注释即可<script src='lang/translator.js' type='text/javascript'></script>然后打开URL就可以看到前端界面了, 应该是没内容的, 因为还没生成swagger.json, 生成好之后你设置的URL就起了作用, 直接访问前端就好
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<script src='lang/zh-cn.js' type='text/javascript'></script>
http://localhost/yii2/swagger-ui/dist/index.html2, 安装后端
git clone https://github.com/zircote/swagger-php.git因为公司用的是yii2, 所以使用了composer来安装
"require": { "zircote/swagger-php": "*" }之后composer update, 或者直接命令行, 详见官方安装指南。DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php把swagger-php放在根目录下，然后用官方提供的Examples来生成测试json
cd swagger-php"-o" 前面代表API源目录, 即你想要生成哪个目录的API文档, 你的项目代码目录. "-o" 后面是生成到哪个path。我没有进入到swagger-php下面, 直接打的命令行, 任意路径下都可以执行生成json操作
mkdir doc
php swagger.phar Examples -o doc
php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs然后再看http//localhost/yii2/swagger-ui/dist/index.html, 生成了API文档。
准备工作都做好了, 那就写代码注释就行了, 注释怎么写? 官方参考文档
比如Model：
/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
* @SWG\Property(name="hostname", type="string"),
* @SWG\Property(name="label", type="string"),
* @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
// ...
}
比如Controller：
/**每次改动API代码注释之后都要手动生成json文件? 太麻烦了, 写了个controller, 每次访问swagger-ui的这个controller, 先生成json再跳转到ui页面。
* @SWG\Resource(
* basePath="http://skyapi.dev",
* resourcePath="/vps",
* @SWG\Api(
* path="/vps",
* @SWG\Operation(
* method="GET",
* type="array",
* summary="Fetch vps lists",
* nickname="vps/index",
* @SWG\Parameter(
* name="expand",
* description="Models to expand",
* paramType="query",
* type="string",
* defaultValue="vps,os_template"
* )
* )
* )
* )
*/
class VpsController extends Controller
{
// ...
}
$b2broot = Yii::getAlias('@b2broot');
$swagger = \Swagger\scan($b2broot.'/myapi');
$json_file = $b2broot.'/swagger-docs/swagger.json';
$is_write = file_put_contents($json_file, $swagger);
if ($is_write == true) {
$this->redirect('http//localhost/yii2/swagger-ui/dist/index.html');
}参考文档：https://www.cnblogs.com/handongyu/p/6992367.html
项目调研：Swagger - RESTFUL接口的文档在线自动生成功能测试框架
zkbhj 发表了文章 • 0 个评论 • 592 次浏览 • 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.
使用Git命令合并分支代码
zkbhj 发表了文章 • 0 个评论 • 329 次浏览 • 2017-12-05 11:05
合并步骤：
1、进入要合并的分支（如开发分支合并到master，则进入master目录）git pull
2、查看所有分支是否都pull下来了git branch -a
3、使用merge合并开发分支git merge 分支名
4、查看合并之后的状态git status
5、有冲突的话，通过IDE解决冲突；
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu)
$ git merge master
Auto-merging mobile/modules/ziroomer/controllers/LdxController.php
CONFLICT (content): Merge conflict in mobile/modules/ziroomer/controllers/LdxCon troller.php
Auto-merging mobile/config/main.php
Auto-merging crontab/controllers/ZiroomerController.php
CONFLICT (content): Merge conflict in crontab/controllers/ZiroomerController.php
Auto-merging common/config/prod/params.php
Automatic merge failed; fix conflicts and then commit the result.
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add mobile/modules/ziroomer/controllers/LdxController.php
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add crontab/controllers/ZiroomerController.php
6、解决冲突之后，将冲突文件提交暂存区git add 冲突文件
7、提交merge之后的结果git commit
如果不是使用git commit -m "备注" ，那么git会自动将合并的结果作为备注，提交本地仓库；
8、本地仓库代码提交远程仓库git push
git将分支合并到分支，将master合并到分支的操作步骤是一样的； 查看全部
1、进入要合并的分支（如开发分支合并到master，则进入master目录）git pull
2、查看所有分支是否都pull下来了git branch -a
3、使用merge合并开发分支git merge 分支名
4、查看合并之后的状态git status
5、有冲突的话，通过IDE解决冲突；
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu)
$ git merge master
Auto-merging mobile/modules/ziroomer/controllers/LdxController.php
CONFLICT (content): Merge conflict in mobile/modules/ziroomer/controllers/LdxCon troller.php
Auto-merging mobile/config/main.php
Auto-merging crontab/controllers/ZiroomerController.php
CONFLICT (content): Merge conflict in crontab/controllers/ZiroomerController.php
Auto-merging common/config/prod/params.php
Automatic merge failed; fix conflicts and then commit the result.
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add mobile/modules/ziroomer/controllers/LdxController.php
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add crontab/controllers/ZiroomerController.php
6、解决冲突之后，将冲突文件提交暂存区git add 冲突文件
7、提交merge之后的结果git commit
如果不是使用git commit -m "备注" ，那么git会自动将合并的结果作为备注，提交本地仓库；
8、本地仓库代码提交远程仓库git push
git将分支合并到分支，将master合并到分支的操作步骤是一样的； 查看全部
合并步骤：
1、进入要合并的分支（如开发分支合并到master，则进入master目录）
2、查看所有分支是否都pull下来了
3、使用merge合并开发分支
4、查看合并之后的状态
5、有冲突的话，通过IDE解决冲突；
6、解决冲突之后，将冲突文件提交暂存区
7、提交merge之后的结果
如果不是使用git commit -m "备注" ，那么git会自动将合并的结果作为备注，提交本地仓库；
8、本地仓库代码提交远程仓库
git将分支合并到分支，将master合并到分支的操作步骤是一样的；
1、进入要合并的分支（如开发分支合并到master，则进入master目录）
git pull
2、查看所有分支是否都pull下来了
git branch -a
3、使用merge合并开发分支
git merge 分支名
4、查看合并之后的状态
git status
5、有冲突的话，通过IDE解决冲突；
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu)
$ git merge master
Auto-merging mobile/modules/ziroomer/controllers/LdxController.php
CONFLICT (content): Merge conflict in mobile/modules/ziroomer/controllers/LdxCon troller.php
Auto-merging mobile/config/main.php
Auto-merging crontab/controllers/ZiroomerController.php
CONFLICT (content): Merge conflict in crontab/controllers/ZiroomerController.php
Auto-merging common/config/prod/params.php
Automatic merge failed; fix conflicts and then commit the result.
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add mobile/modules/ziroomer/controllers/LdxController.php
Administrator@ZKBHJ-PC MINGW64 /i/GIT/activity2 (feature-ziruyu|MERGING)
$ git add crontab/controllers/ZiroomerController.php
6、解决冲突之后，将冲突文件提交暂存区
git add 冲突文件
7、提交merge之后的结果
git commit
如果不是使用git commit -m "备注" ，那么git会自动将合并的结果作为备注，提交本地仓库；
8、本地仓库代码提交远程仓库
git push
git将分支合并到分支，将master合并到分支的操作步骤是一样的；
