标签: spring-restdocs

我正在遵循 Spring Rest Docs 参考文档中关于构建配置的说明。但是当我尝试做时，“片段”属性似乎没有暴露给 Asciidoctor

include::{snippets}/....

但我得到一个 asciidoctor“警告：删除包含对缺失属性的引用的行：片段”

如果我去掉属性引用，直接放在路径中，就会出现包含文件的内容。

这是包含 Rest Docs/Asciidoctor 信息的 build.gradle 文件：

buildscript {
    ext {
        springBootVersion = '1.3.0.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

plugins {
    id "org.asciidoctor.convert" version "1.5.3"
}


allprojects {
    apply plugin: 'groovy'
    apply plugin: 'idea'

    sourceCompatibility = 1.8
    targetCompatibility = 1.8
    group = 'com....'

    ext {
        si = [version: '4.1.7.RELEASE']
        groovy = [version: '2.4.5']
        newRelic = [version: '3.13.0']
        jackson = [version: '2.6.2']
    }

    repositories {
        mavenCentral()
        maven …

我将 Spring 测试迁移到 JUnit 5，它们运行良好。但是，我不知道如何迁移@Rule public JUnitRestDocumentation restDocumentation = ...。任何提示表示赞赏。

我开始使用Spring REST Docs来记录一个简单的REST API.我有一个有一些层次结构的有效负载,例如像这样(有员工的公司).

{
    "companyName": "FooBar",
    "employee": 
    [
        {
            "name": "Lorem",
            "age": "42"
        },

        {
            "name": "Ipsum",
            "age": "24"
        }
    ]
}

我想分离公司对象(员工的姓名和数组)和员工对象(员工姓名和年龄)的文档.

使用这里org.springframework.restdocs.payload.PayloadDocumentation.responseFields解释的类似强制我记录所有字段,但万一我只想记录员工字段 - 我怎样才能实现这一目标？

在没有员工详细信息的情况下记录公司没有问题,因为如果字段是文档,则后代也被视为已记录.但我无法单独记录员工结构,如果没有公司根对象,我没有专门的有效负载.

作为开发人员,我更喜欢spring restdocs.但作为文档的使用者,我发现swagger实时文档非常引人注目.这是无处不在的例子:http://petstore.swagger.io/

有没有办法用spring restdocs记录我的休息api,但生成像swagger petstore这样的实时文档？如果是这样,你怎么做？

我正在尝试将Spring REST文档与Grails 3.1.4应用程序放心.我正在使用JSON视图.

完整代码位于https://github.com/rohitpal99/rest-docs

在我使用的NoteController中

List<Note> noteList = Note.findAll()
Map response = [totalCount: noteList.size(), type: "note"]
render response as grails.converters.JSON

文档生成效果很好.

但我想使用像JSON这样的视图

respond Note.findAll()

我在/ views目录中有_notes.gson和index.gson文件.我得到一个SnippetException.通常/注释GET请求响应是正确的.

rest.docs.ApiDocumentationSpec > test and document get request for /index FAILED
    org.springframework.restdocs.snippet.SnippetException at ApiDocumentationSpec.groovy:54

没有消息.无法跟踪它发生的原因.请建议.

完整的堆栈跟踪

    org.springframework.restdocs.snippet.SnippetException: The following parts of the payload were not documented:
{
  "instanceList" : [ {
    "title" : "Hello, World!",
    "body" : "Integration Test from Hello"
  }, {
    "title" : "Hello, Grails",
    "body" : "Integration Test from Grails"
  } …

我正在构建一个API并使用Spring Rest Docs（1.1.1.RELEASE）对其进行文档记录，还有一个api以字节数组形式返回图像。

我需要在REST文档中描述响应类型。我不确定如何使用FieldDescriptor做到这一点

当我尝试：

//get mock byte array
byte[] attachment = "Hello".getBytes();

FieldDescriptor[] contentFields = new FieldDescriptor[] {
            fieldWithPath("").type(byte[].class)
                    .description("bytes of the attachment ")};

    when(serviceMock.getImage("fe329638007b4ea3b2a5")).thenReturn(attachment);

    this.mockMvc
            .perform(RestDocumentationRequestBuilders.get("/api/v1/contents/{contentId}/images", "fe329638007b4ea3b2a5"))
            .andExpect(status().isOk()).andDo(document("{method-name}",
                    pathParameters(parameterWithName("contentId").description("The id of the Content")),
                    responseFields(contentFields)));

    verify(serviceMock, times(1)).getImage("fe329638007b4ea3b2a5");
    verifyNoMoreInteractions(serviceMock);

我收到以下错误

org.springframework.restdocs.payload.PayloadHandlingException: com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'Hello': was expecting ('true', 'false' or 'null')
 at [Source: [B@13866865; line: 1, column: 11]
at org.springframework.restdocs.payload.JsonContentHandler.readContent(JsonContentHandler.java:86)
at org.springframework.restdocs.payload.JsonContentHandler.findMissingFields(JsonContentHandler.java:52)
at org.springframework.restdocs.payload.AbstractFieldsSnippet.validateFieldDocumentation(AbstractFieldsSnippet.java:152)
at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:100)
at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:64)
at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:196)
at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55)
at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:177)
at com.davita.comms.controller.CommsControllerTest.getThumbnailByContentId(CommsControllerTest.java:205)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at …

我已经搜索过，但找不到一种方法来隐藏主页上的部分标题，并且只显示在Table of Contents(:toc:) 中。从此屏幕截图中可以看出，Home和Test是 adoc 文件的外部链接。我只想将其保留在Table of Contents.

我知道可以Table of Contents使用 [discrete] 关键字隐藏部分标题，但是是否可以反之亦然？

这是此屏幕截图的 adoc 文件：

:toc: left
:source-highlighter: highlight.js
:toclevels: 3
:sectlinks:

== <<Home.adoc#, Home>>

== <<Test.adoc#, Test>>

== Title 1

=== Title 1.1

谢谢你！

我对 SpringRestDoc spring-restdocs-mockmvc 版本 2.0.0.RELEASE 有以下问题

org.springframework.restdocs.snippet.SnippetException：在有效负载中找不到具有以下路径的字段：[listName[].k1]

结果是 Body = {"listName":[{"k1":null},{"k1":"text"}]}

这是其余的服务

@EnableAutoConfiguration
@RestController
public class Docs
{
  @GetMapping("/bug")
  public ResponseEntity bug()
  {
    return ResponseEntity.ok(
      new Object()
        {
          public List listName = Arrays.asList(
            new Object(){
              public String k1 = null;
            }
            , new Object(){
              public String k1 = "text";
            }
          );
        }
      );
  }

  public static void main(String[] args) throws Exception
  {
    SpringApplication.run(Docs.class, args);
  }

这是生成文档的测试类

public class DocsTest
{

  @Rule
  public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

  @Autowired
  private …

我有带有 spring-restdocs 的 spring-boot 应用程序，我想在该应用程序中为生成的文档创建端点。使用生成的 html 文档（由 asciidoctor）公开端点的最佳方法是什么？

我可以将 index.html 包含到 jar 文件中，但不知道如何创建将使用该 html 并暴露在外部的端点。此 html 在测试阶段之后和构建 jar 阶段之前生成。

来自官方文档：您可以将您创建的 HTML 文档发布到静态网站，或者将其打包并从应用程序本身提供。

例如，我在“build/asctiidoctor/html5”文件夹中有 index.html 并且想要创建将返回该 index.html 的控制器。

假设我们有以下 API：

@RestController
public class PersonController {
    @GetMapping("/api/person")
    public List<Person> findPeople() {
        return Arrays.asList(new Person("Doe", "Foo", "John"), new Person("Doe", null, "Jane"));
    }
}

模型类如下所示：

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Person {
    private String lastName;
    private String middleName;
    private String firstName;
}

正如您在控制器中看到的，middleName列表中第二个对象的属性是null。我现在正在尝试使用 Spring REST Docs 来记录 API 的属性，因此我编写了以下测试：

@Test
public void findAllReturnsPeople() throws Exception {
    mockMvc.perform(get("/api/person").accept(MediaType.APPLICATION_JSON))
        .andExpect(jsonPath("$.[0].firstName", is("John")))
        .andExpect(jsonPath("$.[0].middleName", is("Foo")))
        .andExpect(jsonPath("$.[0].lastName", is("Doe")))
        .andExpect(jsonPath("$.[1].firstName", is("Jane")))
        .andExpect(jsonPath("$.[1].middleName", nullValue()))
        .andExpect(jsonPath("$.[1].lastName", is("Doe")))
        .andDo(document("person-get", responseFields(
            fieldWithPath("[].firstName").description("The given name of a person"), …