Param Configuration Reference

原理

smalldoc基于 Java源码 、标准注释 以及 Tag 生成文档，所以，参数配置也是基于这三项内容进行的。

1.忽略解析指定参数

在某些情况下，接口所对应method的参数并不需要展示在文档中，例如

@RequestMapping("/test")
public void test(String p, @RequestHeader(HttpHeaders.HOST) String host, HttpServletRequest request, HttpServletResponse response);

上述接口的参数中，

• host 对应着某个请求头，从请求对象中拿取，不需要明确传递，所以无需展示在接口文档中；
• request 、response 分别对应着请求对象与响应对象，无关传参传递，也不需要展示；

所以在上述接口中，只有参数 p 需要展示在文档中。smalldoc是否解析方法的某个参数，取决于在该方法的注释中是否存在对应的@param标签，所以上述接口注释只需要这样写

/**
 * 测试接口
 *
 * @param p 参数p
 */
@RequestMapping("/test")
public void test(String p, @RequestHeader(HttpHeaders.HOST) String host, HttpServletRequest request, HttpServletResponse response);

---

2.库类型参数配置

对于 库类型 参数，除了注释，还需要决定该参数在该接口中是否必传。

• 否 —— 正常写注释

/**
 * @param p 参数p
 */

• 是 —— 只需要在注释后添加@*

/**
 * @param p 参数p@*
 */

---

3.实体类型参数配置

对于 实体类型 参数，与 库类型 相比有些特殊：

• 在接口文档中，参数展示的是实体中的字段，而并非实体本身。
• 在不同方法中，同一 实体类型 作为参数，字段是否展示、是否必须，可以不同。

这种特殊要求，smalldoc基于注释来完成。

实体类型 的参数注释，需要遵照以下格式（格式定义可见command-line-syntax）

@param  参数名  @{(*|**|f1[*])[,[-]f2[*]...]}

解释： 如果没有合适的字段标记@{(*|**|f1[*])[,[-]f2[*]...]}，将打印警告并返回null

1. 字段之间用,隔开。
2. 支持嵌套字段，以.连接
3. 字段后加*表示必须，无*表示否。
4. *单独出现表示展示所有非继承非实体字段，且是不必须。
5. **单独出现表示展示所有非继承非实体字段，且必须。
6. 在花括号中，*和**不能同时出现，且必须第一个出现。
7. 在*和**后出现的字段
   1. 如果以-开头，并且包含在非继承非实体字段内，则该字段不做展示。
   2. 如果以-开头，但是不包含在非继承非实体字段内，则断言异常发生。
   3. 如果没有以-开头，并且包含在非继承非实体字段内则复写它，通常用来改变必须性。
   4. 如果没有以-开头，并且没有包含在非继承非实体字段内同时包含在合法字段内，则增加显示该字段。
   5. 如果没有以-开头，并且没有包含在非继承非实体字段内但并不包含在合法字段内，则断言异常发生。
8. 集合或实体数组的字段会自动增加[]后缀，表示要采用数组方式提交。