修正 README.md

README.md

@@ -1,7 +1,11 @@
 
+![](https://coding.net/u/hoteam/p/Cache/git/raw/master/2017/6/1/noun_28890_cc.png)
+[![npm version](https://badge.fury.io/js/swagger-decorator.svg)](https://badge.fury.io/js/swagger-decorator)
+
 中文版本 | [English Version](https://github.com/wxyyxc1992/swagger-decorator/blob/master/README.en.md)
 
-> [基于 swagger-decorator 的自动实体类构建与 Swagger 接口文档生成]()，对于不反感使用注解的项目中利用 swagger-decorator 添加合适的实体类或者接口类注解，从而实现支持嵌套地实体类校验与生成、Sequelize 等 ORM 模型生成、基于 Swagger 的接口文档生成等等功能。
+
+> [基于 swagger-decorator 的自动实体类构建与 Swagger 接口文档生成](https://zhuanlan.zhihu.com/p/27941329)是笔者对于开源项目[ swagger-decorator ](https://github.com/wxyyxc1992/swagger-decorator)的描述，对于不反感使用注解的项目中利用 swagger-decorator 添加合适的实体类或者接口类注解，从而实现支持嵌套地实体类校验与生成、Sequelize 等 ORM 模型生成、基于 Swagger 的接口文档生成等等功能。如果有对 JavaScript 语法使用尚存不明的可以参考[ JavaScript 学习与实践资料索引](https://parg.co/bMI)或者[现代 JavaScript 开发：语法基础与实践技巧](https://parg.co/b1c)系列文章。
 
 # swagger-decorator: 一处注解，多处使用
 
@@ -33,6 +37,8 @@ import {
 
 # 实体类注解
 
+swagger-decorator 的核心 API 即是对于实体类的注解，该注解不会改变实体类的任何属性表现，只是会将注解限定的属性特性记录在内置的 innerEntityObject 单例中以供后用。属性注解 entityProperty 的方法说明如下：
+
 ```javascript
 /**
  * Description 创建某个属性的描述
@@ -59,6 +65,8 @@ export function entityProperty({
 }) {}
 ```
 
+简单的用户实体类注解如下，这里的数据类型 type 支持 Swagger 默认的字符格式的类型描述，也支持直接使用 JavaScript 类名或者 JavaScript 数组。
+
 ```javascript
 // @flow
 
@@ -114,7 +122,7 @@ export default class UserProperty {
 
 ```
 
-数据类型支持：
+Swagger 内置数据类型定义：
 
 | Common Name | [`type`](http://swagger.io/specification/#dataTypeType) | [`format`](http://swagger.io/specification/#dataTypeFormat) | Comments                                 |
 | ----------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- |
@@ -132,6 +140,9 @@ export default class UserProperty {
 
 
 ## 实例生成与校验
+
+实体类定义完毕之后，我们首先可以使用 instantiate 函数为实体类生成实例；不同于直接使用 new 关键字创建，instantiate 能够根据指定属性的数据类型或者格式进行校验，同时能够迭代生成嵌套地子对象。
+
 ```javascript
 /**
  * Description 从实体类中生成对象，并且进行数据校验；注意，这里会进行递归生成，即对实体类对象同样进行生成
@@ -150,6 +161,8 @@ export function instantiate(
 ): Object {}
 ```
 
+这里为了方便描述使用 Jest 测试用例说明不同的使用场景：
+
 ```javascript
 describe("测试实体类实例化函数", () => {
   test("测试 User 类实例化校验", () => {
@@ -229,6 +242,8 @@ describe("测试嵌套实例生成", () => {
 
 ## Sequelize 模型生成
 
+[Sequelize](http://docs.sequelizejs.com/) 是 Node.js 应用中常用的 ORM 框架，swagger-decorator 提供了 generateSequelizeModel 函数以方便从实体类中利用现有的信息生成 Sequelize 对象模型；generateSequelizeModel 的第一个参数输入实体类，第二个参数输入需要覆写的模型属性，第三个参数设置额外属性，譬如是否需要将驼峰命名转化为下划线命名等等。
+
 ```javascript
 const originUserSequelizeModel = generateSequelizeModel(
   User,
@@ -259,14 +274,91 @@ UserSequelizeModel.findAll({
 });
 ```
 
-## 实体类转化与生成工具
+## 从 Flow 类型声明中自动生成注解
+
+笔者习惯使用 Flow 作为 JavaScript 的静态类型检测工具，因此笔者添加了 flowToDecorator 函数以自动地从 Flow 声明的类文件中提取出类型信息；内部原理参考[现代 JavaScript 开发：语法基础与实践技巧](https://parg.co/b1c) 一书中的[ JavaScript 语法树与代码转化](https://parg.co/baS)章节。该函数的使用方式为：
+```
+// @flow
+
+import { flowToDecorator } from '../../../../src/transform/entity/flow/flow';
+
+test('测试从 Flow 中提取出数据类型并且转化为 Swagger 接口类', () => {
+  flowToDecorator('./TestEntity.js', './TestEntity.transformed.js').then(
+    codeStr => {
+      console.log(codeStr);
+    },
+    err => {
+      console.error(err);
+    }
+  );
+});
+
+```
+这里对应的 TestEntity 为：
+```
+// @flow
+
+import AnotherEntity from "./AnotherEntity";
+
+class Entity {
+  // Comment
+  stringProperty: string = 0;
+
+  classProperty: Entity = null;
+
+  rawProperty;
+
+  @entityProperty({
+    type: "string",
+    description: "this is property description",
+    required: true
+  })
+  decoratedProperty;
+}
+
+```
+转化后的实体类为：
+```
+// @flow
+
+import { entityProperty } from 'swagger-decorator';
+
+import AnotherEntity from './AnotherEntity';
+
+class Entity {
+  // Comment
+  @entityProperty({
+    type: 'string',
+    required: false,
+    description: 'Comment'
+  })
+  stringProperty: string = 0;
+
+  @entityProperty({
+    type: Entity,
+    required: false
+  })
+  classProperty: Entity = null;
 
-### 从 Flow 类型声明中自动生成注解
+  @entityProperty({
+    type: 'string',
+    required: false
+  })
+  rawProperty;
 
+  @entityProperty({
+    type: 'string',
+    description: 'this is property description',
+    required: true
+  })
+  decoratedProperty;
+}
+
+```
 
 # 接口注解与 Swagger 文档生成
 
-对于 Swagger 文档规范可以参考[ OpenAPI Specification ](http://swagger.io/specification/)，而对于 swagger-decorator 的实际使用可以参考本项目的[使用示例]()或者[ 基于 Koa2 的 Node.js 应用模板 ](https://parg.co/bvx)。
+对于 Swagger 文档规范可以参考[ OpenAPI Specification ](http://swagger.io/specification/)，而对于 swagger-decorator 的实际使用可以参考本项目的[使用示例](https://parg.co/bac)或者[ 基于 Koa2 的 Node.js 应用模板 ](https://parg.co/bvx)。
 
 
 ## 封装路由对象
@@ -320,6 +412,7 @@ export default class UserController extends UserControllerDoc {
   }
 }
 ```
+在 UserController 中是负责具体的业务实现，为了避免过多的注解文档对于代码可读性的干扰，笔者建议是将除了路径与描述之外的信息放置到父类中声明；swagger-decorator 会自动从某个接口类的直接父类中提取出同名方法的描述文档。
 
 ```javascript
 
@@ -357,7 +450,7 @@ export default class UserControllerDoc {
 
 ```
 
-## 应用运行
+## 运行应用
 
 - run your application and open swagger docs (PS. swagger-decorator contains Swagger UI):
 ```text