使用 Spock 从 Spring Rest 文档生成 ascii doc api 文档

Question

我正在尝试为我的 Spring Boot 应用程序（版本：2.7.5）编写 Spock 测试用例，并且我想使用 Spring REST Docs 生成 AsciiDoc 文档。有人可以提供示例工作代码片段来演示如何实现这一目标吗？

这是我迄今为止尝试过的：

build.gradle

plugins { 
    id 'org.springframework.boot' version '2.7.5'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'groovy'
    id "org.asciidoctor.convert" version "1.5.8.1"
}

group = 'co.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

ext { 
    snippetsDir = file('build/generated-snippets')
}

dependencies {
     ...
     implementation 'org.springframework.restdocs:spring-restdocs-restassured:2.0.5.RELEASE'
    implementation 'org.springframework.restdocs:spring-restdocs-core:2.0.5.RELEASE'
    implementation 'org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.5.RELEASE'
    testImplementation 'junit:junit:4.13.2'
    ...
}


test { 
    outputs.dir snippetsDir
}

asciidoctor { 
    inputs.dir snippetsDir 
    dependsOn test 
}

LeadControllerSpec

class LeadControllerSpec extends Specification {

    @Rule
    JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation() // TODO: need to give path

   
    RequestSpecification documentationSpec

    void setup() {
        this.documentationSpec = new RequestSpecBuilder()
                .addFilter(RestAssuredRestDocumentation.documentationConfiguration(restDocumentation)
                .operationPreprocessors()
                        .withRequestDefaults(
                                Preprocessors.modifyUris().host('api.example.com')
                                        .removePort())
                        .withResponseDefaults(Preprocessors.prettyPrint()))
                .build()
    }

    void cleanup() {

    }

    def "test createLead endpoint"() {
        when:
        def response = RestAssured.given(this.documentationSpec)
                .accept(MediaType.APPLICATION_JSON_VALUE)
                .contentType(MediaType.APPLICATION_JSON_VALUE)
                .body([
                        firstName: "John",
                        lastName: "Doe",
                        mobileNumber: "1234567890",
                        emailId: "[email protected]",
                        pincode: "12345",
                        cardScheme: "SchemeA"
                ])
                .when()
                .post("/api/v1/lead/create")

        then:
        response.statusCode == 200
    }
}

如有任何帮助，我们将不胜感激。预先感谢！

Answer 1

您使用

@Rule

的代码看起来像 JUnit 4，但 Spock 2.x 基于 JUnit 5，即该方法可能不起作用，除非您正在使用 Spock 1.x。

我很好奇，尝试从头开始建立一个 Maven 项目 - 抱歉，请自行将其转换为 Gradle：

https://github.com/kriegaex/SO_Spock_SpringRESTDocs_78424426

示例应用程序如下：

package org.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    new SpringApplication(Application.class).run(args);
  }

  @RestController
  private static class SampleController {
    @RequestMapping("/")
    public String index() {
      return "Hello, World";
    }
  }
}

相应的Spock规范看起来像这样：

package org.example

import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.restdocs.ManualRestDocumentation
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.setup.MockMvcBuilders
import org.springframework.web.context.WebApplicationContext
import spock.lang.Specification

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status

@SpringBootTest(classes = [Application])
class MyControllerSpec extends Specification {
  def restDocumentation = new ManualRestDocumentation()
  @Autowired
  WebApplicationContext context
  MockMvc mockMvc

  def setup() {
    mockMvc = MockMvcBuilders
      .webAppContextSetup(context)
      .apply(documentationConfiguration(restDocumentation))
      .build()
    restDocumentation.beforeTest(getClass(), specificationContext.currentFeature.displayName)
  }

  def cleanup() {
    restDocumentation.afterTest()
  }

  def "should document the GET /hello endpoint"() {
    expect:
    mockMvc
      .perform(get("/"))
      .andExpect(status().isOk())
      .andDo(document("sample"))
  }
}

基本上，我将手册中描述的“非 JUnit 设置”调整为 Spock。从提供的示例项目我复制了 TestNG 的代码。 让 Spring 和 Spring REST Docs 的各种产品版本匹配并与 Spock 配合得很好，有点棘手，但在我的示例项目中它现在工作得很好。