Spring MVC使用说明
- 支持的注解
针对Spring framework的web服务框架，wrdoclet主要是利用注解来识别服务接口以及参数。比如@RequestMapping，@ResponseBody，@Controller等。因为Spring framework注解较多，目前wrdoclet还有一部分注解没有支持，比如@SessionAttributes, @ModelAttribute等。
- 登录态
web服务框架通常涉及登录，并且通过interceptor来实现登录token验证的比较多。为了能在接口文档中标示接口是否需要用户登录，wrdoclet可以尝试分析mvc的配置文件，从而确定哪些接口需要登录后才能使用。
<mvc:interceptors>
<mvc:interceptor>
<mvc:mapping path="/**" />
<mvc:exclude-mapping path="/*/getgender/*"/>
<bean class="net.winroad.Interceptor.LoginInterceptor">
<property name="excludedUrls">
<list>
<value>/class/list</value>
<value>/student/login</value>
</list>
</property>
</bean>
</mvc:interceptor>
</mvc:interceptors>
wrdoclet在运行过程中无法知道mvc的配置文件的具体地址，因此需要在执行时明确传入该配置文件的绝对地址，以及用于识别那些无需登录的URL地址的XPATH。下面就是demo中生成文档时所使用的参数。
"-springcontextconfigpath",
"D:/Git/wrdoclet/wrdoclet-demosite/src/main/webapp/WEB-INF/mvc-dispatcher-servlet.xml",
"-excludedurlsxpath",
"//:beans/mvc:interceptors/mvc:interceptor/:bean/:property/:list/:value",
系统通过自定义注解来实现登录态的处理也是比较常见的，wrdoclet也可以在生成文档时使用 -authkeyword 和 -noauthkeyword 来帮助识别哪些接口需要验证登录，哪些则不需要。-authkeyword 和 -noauthkeyword 都是指定一些关键词，这些关键词使用","进行分割。当接口函数使用的注解包含 -authkeyword 中的某一个关键词时，则表示该接口必须要验证登录通过后方可被调用。当接口函数使用的注解包含 -noauthkeyword 中的某一个关键词时，则表示该接口不需要验证登录通过就可被调用。
下面就是demo中生成文档时所使用的参数。
-authkeyword REQUEST_COOKIE_AUTH,REQUEST_BODY_AUTH
-noauthkeyword NO_AUTH,OPTIONAL_AUTH
- 指定注解显示
有的时候系统接口使用了一些注解，希望这些注解也能直接在接口文档中展现出来，这样有助于帮助接口文档的阅读者来理解接口的使用方法。 wrdoclet也在1.2.0版本中增加了 -showannotationlist 参数。 通过该参数指定一批用","分割的注解（包含package名称）。
下面就是demo中生成文档时所使用的参数。
-showannotationlist net.winroad.Models.LoginAuthority,org.springframework.web.bind.annotation.RequestMapping
- 指定序列化
Spring MVC 常见的接口返回是使用注解@ResponseBody, 采用默认配置返回json。但也有场景使用返回的Bean中有一些字段是不希望被返回给客户端的，因此有些开发者会自定义序列化的配置（具体可参见https://github.com/WinRoad-NET/wrdoclet-demo 中wrdoclet-demosite下的 @JsonResult 的使用）。 wrdoclet在1.2.3版本中增加了-cmzfieldexclude 和 -cmzfieldinclude配置参数，通过配置开发者自己定义的注解来指定包含的序列化字段或者指定需要排除的序列化字段。
在wrdoclet-demosite中开发者自定义了@JsonResult注解，该注解属性include可指定在对bean进行json序列化时的属性名称；注解属性exclude可指定在对bean进行json序列化时需要排除的属性名称。