example

@egname, @egvalue, @egexternalvalue, @egsummary, @egdescription是自定义taglet。主要是功能是给参数添加示例。@egvalue, @egexternalvalue, @egsummary, @egdescription分别对应 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#exampleObject 中的value, externalValue, summary, description。 参数example示例的相关内容会在生成的文档的“示例及修订记录”一列中显示。

当这些taglet使用在接口方法上时，需要为其指定对应的接口方法参数。例如下面的例子中给student和username参数注释了示例。student参数为一个bean对象，该示例可以使用换行的形式对对象中各个属性值分别进行示例描述。

/**
 * 
 * @param student
 * @param username 名称
 * @egvalue student 
 * - username Bill Gates
 * - gender MALE
 * - age 68
 * - adult true
 * - height 182.8
 * - address
 *      - province beijing
 * @egname username examplename
 * @egsummary username summary of username
 * @egvalue username Kevin 
 * Smith
 * @egdescription username 这是学生的姓名， 可以通过姓名来删除
 * @return
 */
@RequestMapping(value = "/delete/{name}", method = RequestMethod.POST)
public @ResponseBody
String delStudent(@RequestBody(required=false) Student student,
        @PathVariable("name") String username) {
    return "delete name:" + username + "/" + student.getName();
}

当这些taglet使用在bean的field或者getter、setter方法上时，则不用指定参数名称。例如

public class Person implements Serializable{
    ...
    /**
     * @egsummary 性别
     * @egvalue MALE
     */
    private Gender gender;
    private Color color;
    ...
}