修改历史

优秀的接口文档常常还会对接口或者参数的修改历史进行详细的描述,方便接口使用者了解接口变更情况。

为了展示修改历史,需要使用三个taglet,分别是@author 修改人, @version 修改发生的时间, @memo 所作修改的描述。在描述修改记录时,根据“谁在什么时候做了什么事”为原则,注释顺序是@author, @version, @memo。

接口修改记录的例子:

/**
 * 删除课程 
 * @tag Class, School
 * @author Adams 
 * @version 0.0.1 
 * @memo init add api 
 * @author Bob 
 * @version 0.0.2 
 * @memo fix bug
 * @returnCode 400 404 503
 */
@RequestMapping(value = "/class/del", method = RequestMethod.POST)
public @ResponseBody
Clazz delClass(@RequestBody Clazz clazz, HttpServletRequest httpRequest,
        HttpServletResponse httpResponse) {
    return clazz;
}

参数修改记录的例子

public class Clazz {

    /**
     * 课程名称
     * 
     * @author Bob huang
     * @version 0.0.2
     * @memo fix bla bla bla bla bla bla bla bla bug
     * @occurs required
     */
    public String getName() {
        return name;
    }
}

results matching ""

    No results matching ""