未创建 Spring Rest 文档片段

Question

我试图在我的项目中应用 Spring Rest 文档，所以我遵循了官方参考网站的指南。但我无法制作任何片段。

这是我的 build.gradle。

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.0'
    id 'io.spring.dependency-management' version '1.1.5'
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

group = 'study'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

configurations {
    asciidoctorExt
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-web'

    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'org.mariadb.jdbc:mariadb-java-client'
    annotationProcessor 'org.projectlombok:lombok'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    testImplementation 'org.springframework.security:spring-security-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    implementation 'io.jsonwebtoken:jjwt-api:0.12.3'
    implementation 'io.jsonwebtoken:jjwt-impl:0.12.3'
    implementation 'io.jsonwebtoken:jjwt-jackson:0.12.3'

    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
}

tasks.named('test') {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

tasks.named('asciidoctor') {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

tasks.register('copyDocument', Copy) {
    dependsOn asciidoctor

    from file("build/docs/asciidoc/")
    into file("src/main/resources/static/docs")
}

build {
    dependsOn copyDocument
}

这是我的测试。

private static final Logger log = LoggerFactory.getLogger(SsenseApplicationTests.class);
    private MockMvc mockMvc;
    @Autowired
    ObjectMapper objectMapper;

    @RegisterExtension
    final RestDocumentationExtension restDocumentation = new RestDocumentationExtension("custom");

    @BeforeEach
    void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup((webApplicationContext))
                .apply(documentationConfiguration(restDocumentation))
                .apply(springSecurity())
                .build();
    }

    @Test
    @Transactional
    void join() throws Exception {
        this.mockMvc.perform(post("/join")
                        .param("username", "test")
                        .param("password", "1234"))
                .andDo(print())
                .andExpect(status().isOk())
                .andDo(document("join", formParameters(
                        parameterWithName("username").description("username"),
                        parameterWithName("password").description("password")
                        )
                ));
    }

    @Test
    void login() throws Exception {
        this.mockMvc.perform(formLogin().user("test").password("1234"))
                .andDo(print())
                .andExpect(status().isOk())
                .andDo(document("login",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint())));
    }

测试效果很好。我尝试了一切，这是我能得到的最好的，但它仍然没有创建任何片段。帮助我

Answer 1

您提供的配置和测试代码对于生成 Spring REST 文档片段似乎是正确的。但是，您可以检查一些事项来排除未生成代码片段的原因：
检查测试的输出：如果 Spring REST Docs 由于某种原因无法生成代码片段，则测试将失败。如果测试通过但没有生成代码片段，则可能是没有调用 document() 方法。确保在测试中调用 andDo(document(...)) 方法。
检查生成的代码片段的位置：代码片段应在 build.gradle 文件中的 snippetsDir 属性指定的目录中生成。就您而言，这是构建/生成的片段。确保此目录存在并且您的应用程序对其具有写访问权限。
检查 Spring REST 文档的版本：确保您使用的 Spring REST 文档版本与您正在使用的 Spring Boot 版本兼容。
检查您的 asciidoctor 任务：确保 build.gradle 文件中的 asciidoctor 任务已正确配置，以将生成的片段转换为文档。
如果您已经检查了所有这些内容，但仍然没有看到代码片段，那么创建一个重现问题的最小独立项目可能会有所帮助。这可以帮助您隔离问题，也可以让其他人更轻松地帮助您诊断问题。