swagger

Author: viper140

backend/java-code-guideline.md

@@ -242,4 +242,11 @@ HTTP/1.1 200
 
 ## 18. 锁的使用
 
-尽可能避免表级别的锁。如果很多需要串行处理的操作，可以建立一个辅助的只有一行的semaphore（信号）表，事物开始时先修改这个表，然后进行其他业务处理。
+尽可能避免表级别的锁。如果很多需要串行处理的操作，可以建立一个辅助的只有一行的semaphore（信号）表，事物开始时先修改这个表，然后进行其他业务处理。
+
+## 19. java中使用swagger
+
+针对`io.springfox:springfox-swagger2`的使用，我们要注意：
+
+1. @ApiModel注解value属性值不能写中文，会导致swagger导出json时会报错。建议直接不写参数。
+2. 任何swagger注解的属性值都不要有单引号，json不认识单引号，swagger导出json会报错。比如@ApiModelProperty注解example属性值我们有时候希望给复杂类型（比如"['111','222']"）。遇到这种情况，我们不写example。

backend/swagger-usage-guideline.md

@@ -14,8 +14,8 @@
 
 ```java
 @ApiOperation(
-    value = "员工登陆",
-    notes = "根据用户名和密码进行登陆认证</br>"
+    value = "员工登录",
+    notes = "根据用户名和密码进行登录认证</br>"
         + "code = 1: 密码错误</br>"
         + "code = 2: 用户名不存在"
     )
@@ -36,15 +36,16 @@
 
 - 参数若为类对象：
 
-  - 类名上需加如下注释，用于说明此对象参数的名称：
+  - 类名上需加如下注释，用于说明此对象参数的名称：（这个注解完全没必要用）
+    - value：对象参数名。特别注意：**value不要用中文**，会导致swagger导出json失败
 
-  ```java
-  @ApiModel(value = "登陆信息")
-  ```
+    ```java
+    @ApiModel(value = "xxx")
+    ```
 
   - 类中字段需在 @ApiModelProperty 注解中加如下说明：
     - value：表示字段名
-    - example：表示该字段的示例值，在测试时很有帮助
+    - example：表示该字段的示例值，在测试时很有帮助，但是，千万不要有单引号，遇到复杂类型，宁可不写example
     - required: 若为必携带的参数，则为true
 
     ```java