注解引用文件

其实基于注解的文档说明已经能应付大部分的使用场景了。

那么剩下小部分比较特殊的使用场景，例如某个接口业务逻辑比较复杂，需要长篇累牍去说明，甚至需要做一些排版使得读者更容易理解，这个时候注解显然是难以胜任的。那么 Leap 对此有没有解决方案呢？答案是有的。

同样还是回到上一节提到的 @Doc 注解，其实这个注解除了在里面写说明文档，还可以写 Leap 支持的文档引用表达式，表达式语法为：

doc:md文件名.md

例如我们在接口方法上的注解中这样写：

@Doc("doc:pet_find.md")
public ApiResponse<Pet> find(@Required String id) {
    return null;
}

所有文档引用表达式都以 doc: 开头，以便 Leap 识别。后面接上的内容就是 Markdown 文件的位置，一般以 md 为文件后缀。这个例子的意思就是 find 这个接口方法将 pet_find.md 文件中的内容作为文档说明。

那 Leap 会去哪里找这个 md 文件呢？我们在这里约定，资源 resource 文件夹下的 doc 目录就是 md 文档的根。所以在上例中，find 接口方法的文档最终会以 /doc/pet_find.md 的内容渲染。