如何使用Znai将Java测试方法示例嵌入Markdown文档

1. 标记待提取的测试示例 #

你不需要改动现有测试方法的执行逻辑，只要在MyExamplesTest里需要同步到文档的测试方法上添加Znai提供的@Example注解，给每个示例配置唯一id和展示标题即可，参考写法：

import org.junit.jupiter.api.Test;
import com.twosigma.znai.java.annotations.Example;

public class MyExamplesTest {

    @Test
    @Example(id = "user-create-api-demo", title = "创建用户接口调用示例")
    public void testCreateUserApi() {
        // 原有测试逻辑：初始化客户端、构造请求、调用接口、断言结果
        ApiClient client = new ApiClient("https://api.yourdomain.com");
        CreateUserRequest req = new CreateUserRequest().setName("test").setAge(20);
        UserResp resp = client.createUser(req);
        assertEquals(200, resp.getCode());
    }
}

如果不想改动测试类代码，后续嵌入时直接指定类名+方法名也能提取，但给示例配置固定id的方式更稳定，不会因为后续重构改方法名导致文档引用失效。
如果测试方法里有测试专用逻辑（比如mock依赖、测试数据初始化、断言语句）不想展示在文档里，可以用Znai的注释标记包裹需要隐藏的片段：

// znai:hide-start
// 这里写需要隐藏的测试专用逻辑，比如mock初始化、断言代码
// znai:hide-end

提取时这部分内容会被自动过滤，文档里只保留核心的API调用逻辑。

2. 配置Znai扫描规则 #

在文档项目的Znai配置文件（通常命名为znai.config）中，添加Java示例的扫描配置，指定测试类的扫描路径即可：

{
  "javaExamples": {
    "scanDirs": ["./src/test/java/com/yourdomain/test/MyExamplesTest.java"],
    "stripAssertions": true, // 可选：全局配置是否自动过滤断言语句
    "hideImports": false // 可选：全局配置是否隐藏import导入语句
  }
}

3. Markdown文档中嵌入示例 #

编写Markdown文档时，不需要手动复制粘贴测试代码，直接使用Znai的Java示例嵌入标记，传入之前配置的示例id即可：

:include-java: exampleId=user-create-api-demo

你也可以根据展示需求在嵌入标记里加自定义参数：

• 未加@Example注解的方法，可直接指定类名和方法名引用：:include-java: className=MyExamplesTest, methodName=testCreateUserApi
• 需要高亮指定代码行时，加highlightedLines=2,4参数
• 需要覆盖全局配置保留断言/import语句时，加keepAssertions=true或showImports=true参数

Znai执行文档构建时，会自动从测试类中拉取对应方法的最新代码，渲染为标准Markdown代码块。由于引用的代码是可正常执行的JUnit测试用例，CI流程运行测试时如果发现示例逻辑和API实际实现不匹配，会直接阻断文档构建，从根源上避免文档示例过期、跑不通的问题。

内容的提问来源于stack exchange，提问作者Mykola Golubyev