标签: spring-restdocs

Spring REST Docs最近发布,文档说:

这种方法使您免受Swagger等工具的限制

所以,我想问一下,当Spring REST Docs与Swagger比较时,以及它可以解除的限制.

当使用pathParameters记录URI路径参数,如下面

@Test
public void documentGetRouteById() throws Exception {
    this.mockMvc.perform(get("/route/{id}", "FooBar")).andExpect(status().isOk())
            .andDo(document("api-getRouteById",
                    pathParameters(parameterWithName("id").description("die Routen ID"))));
}

我得到以下激励

java.lang.IllegalArgumentException: urlTemplate not found. Did you use RestDocumentationRequestBuilders to build the request?
    at org.springframework.util.Assert.notNull(Assert.java:112)
    at org.springframework.restdocs.request.PathParametersSnippet.extractUrlTemplate(PathParametersSnippet.java:95)
    at org.springframework.restdocs.request.PathParametersSnippet.extractActualParameters(PathParametersSnippet.java:82)
    at org.springframework.restdocs.request.AbstractParametersSnippet.verifyParameterDescriptors(AbstractParametersSnippet.java:77)
    at org.springframework.restdocs.request.AbstractParametersSnippet.createModel(AbstractParametersSnippet.java:65)
    at org.springframework.restdocs.request.PathParametersSnippet.createModel(PathParametersSnippet.java:67)
    at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:64)
    at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:101)
    at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:158)

我敢肯定,我做了测试设置类似解释在这里.

我可能做错了什么？

(Spring REST docs版本是1.0.0.BUILD-SNAPSHOT)

我使用Spring REST Docs来记录REST API.我正在尝试记录以下API操作:

GET /subsystems
GET /subsystems/some_name

例如,调用GET /subsystems/samba返回以下JSON对象:

{ 
  "id": "samba", 
  "description": "..." 
}

您可以使用以下代码片段来使用Spring REST Docs来记录此API操作:

this.mockMvc.perform(
    get("/subsystems/samba").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("id").description("Subsystem name"),
            fieldWithPath("description").description("Subsystem description")));

我的问题是第一个操作:调用GET /subsystems返回一个JSON数组:

[ 
  { 
    "id" : "samba", 
    "description" : "..." 
  }, 
  { "id" : "ownCloud", 
    "description" : "..." 
  },
  { "id" : "ldap", 
    "description" : "..." 
  } 
]

我找不到任何显示如何在Spring REST Docs文档中记录此类结果的示例.我该怎么办？

我的应用正在使用spring-data-rest和spring-restdocs.我的设置非常标准; 几乎完全从文档中复制,但我已经包含了下面的示例,以防我遗漏了一些东西.当我的mvc测试运行时,它失败了:

org.springframework.restdocs.snippet.SnippetException: The following parts of the payload were not documented:
{
  "_links" : {
    "self" : {
      "href" : "https://my-api/item/10"
    },
    "item" : {
      "href" : "https://my-api/item/10"
    }
  }
}

这是我的测试代码:

@Rule
public JUnitRestDocumentation restDocs = new JUnitRestDocumentation("target/generated-snippets");
// ...
mockMvc = webAppContextSetup(wac) //WebApplicationContext
        .apply(documentationConfiguration(restDocs)
                       .uris()
                       .withHost("my-api")
                       .withPort(443)
                       .withScheme("https"))
        .build();
// ....
mockMvc.perform(get("/items/{id}", "10"))
               .andDo(documentation)

这是堆栈:

at org.springframework.restdocs.payload.AbstractFieldsSnippet.validateFieldDocumentation(AbstractFieldsSnippet.java:176)
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.example.my.api.domain.MyRepositoryRestTest.findOne(MyRepositoryRestTest.java:36)

我如何获得spring-restdocs和spring-data-rest …

我一个接一个地遵循了Spring Rest Doc的入门指南,但我无法从生成的片段中获取任何html.

片段在我配置的目录(build/generated-snippets)中生成正常,但我看不到任何html5 /目录,其中包含从片段生成的html文件.

doc 在某些方面说明了如何将文档打包到jar中,很明显它需要一些html5 /目录中的文件,但是在构建运行时不会创建:

dependsOn asciidoctor
from("${asciidoctor.outputDir}/html5") {
    into 'static/docs'
}

我错过了什么？

我的项目文件build.gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.3.5.RELEASE'
    }
}

plugins {
    id 'org.asciidoctor.convert' version '1.5.2'
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'spring-boot'
apply plugin: 'jacoco'
apply plugin: 'war'

sourceCompatibility = 1.8
targetCompatibility = 1.8

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

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web:1.3.5.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-logging:1.3.5.RELEASE' …

我正在采用 Spring Rest Docs，并且测试成功创建了 *.adoc 文件。

我在 src/docs/asciidoc 目录中创建了 api-guide.doc 文件来创建 html，但是当我将 asciidoc 作为 gradle 任务运行时，它会产生以下错误。

Some problems were found with the configuration of task ':asciidoctor' (type 'AsciidoctorTask').
  - In plugin 'org.asciidoctor.convert' type 'org.asciidoctor.gradle.AsciidoctorTask' method 'asGemPath()' should not be annotated with: @Optional, @InputDirectory.

我用spring初始化器初始化了项目，所以我相信gradle依赖没有问题。

plugins {
    id 'org.springframework.boot' version '2.5.3'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'org.asciidoctor.convert' version '1.5.8'
    id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories { …

Spring REST Docs生成一个curl片段,在测试时非常方便.它等同MockMvc于其文档中所述的调用,但如果它的主机部分可以替换为测试服务器的主机名(包括端口)而不是localhost.是否有可能用它的当前版本来实现它？

我正在使用Spring Rest Docs生成文档.我想做一些像Bootstrap的Togglable标签.

Spring文档使用了可切换的标签,但我不知道该怎么做.这是一个例子(MockMvc/REST Assured):http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/#documenting-your-api 感谢您的帮助.

我是 Spring Boot 的新手。我想从 Spring MVC 控制器自动将 REST api 文档生成到 RAML 中。有什么可以做的吗？或者有什么指南可以让我用它来将我的 REST API 生成到 RAML 中？

我正在尝试在我的项目中设置 spring-auto-restdocs，该项目使用 JDK 11、Gradle 5、JUnit5 和 Spring Webflux 以及 spring boot 2.1.1。

我在这里遵循了正常的 spring-restdocs 设置指南：https ://docs.spring.io/spring-restdocs/docs/current/reference/html5/

然后也做了这个入门指南：https : //scacap.github.io/spring-auto-restdocs/

我的问题是，当我尝试运行以下 gradle 命令时： gradlew asciidoctor --stacktrace

我收到以下错误：

javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.
javadoc: error - invalid …