scacap / spring-auto-restdocs Goto Github PK

I've got a problem with rendered text from annotation @Pattern.
A pipe symbol (|) within a regular expression breaks a table.

Spring Auto REST Docs is creation the following snippet:

|===
|Path|Type|Optional|Description

|id
|Integer
|true
|Item ID. +
javax.validation.constraints.NotBlank.

|description
|String
|true
|Item description. +
Size must be between 0 and 20 inclusive.

|patternString
|String
|true
|This is a regex pattern. +
Must match the regular expression `(TEST)|(LIVE)`.

|===

When HTML-documemnt is created by asciidoc (LIVE) is omitted. Also text isn't rendered in monospace. If one escapes the pipe ((TEST)\|(LIVE) you get the right result.
Can you add escaping of pipe symbols within regular expessions?
I've added a sample project.

I don't think the documentation is generated quite right when using property access control through Jackson. The property I annotated with WRITE_ONLY access showed up in the generated Response Fields section and READ_ONLY shows up in the Request Fields. Is there a plan to add this functionality in the near future or could you point me in the right direction and I could look at creating a PR for this support?

An endpoint that accept page and size parameter, but auto-restdocs failed to document it

    /**
     * index
     *
     * @param page page number
     * @param size size of a page
     */
    @GetMapping
    public Page<Video> index(Pageable pageable) {
        return videoRepository.findAll(QVideo.video.url.eq("http://a.com"), pageable);
    }

example request

curl 'http://localhost:8080/video?page=1&size=5' -i

Article on the Spring Blog: https://spring.io/blog/2017/04/24/spring-rest-docs-1-2-0-release
Release notes: https://github.com/spring-projects/spring-restdocs/wiki/Spring-REST-Docs-1.2-Release-Notes

Currently, we do not set the encoding when writing or reading the JSON files with the Javadoc content. Therefore, it depends on the environment whether characters like Ñ or Ä are handled correctly.

sonatype publishes snapshots, ppl can try them out
#124 (comment)

I've configured the project and generated docs. Everything looked fine. But when I added javadocs and generated docs nothing changed.
What is the reason for such problem?
Here is by build.gradle and tests.

We have polymorphic types as part of our API spec. There is an interface and there are abstract classes and concrete classes that implement the interface and auto-rest-docs appears to ignore the @JsonTypeInfo and @JsonSubTypes annotations. In the documentation that is generated, the field where the interface is used is correctly identified as an "Object". However no documentation is generated for the implementations. What are we missing? Any help is appreciated.

The domain objects for our REST API is in an external library and is shared across our orchestration and domain micro services. Spring-auto-restdocs doesn't read the documentation from the external library (even if we include the source files).

Spring rest docs automatically determines the location for the snippets based on what is in the project. I would propose that you as well do something automatically to determine what kind of project it is and use a default location for the location of the json files.

This is to track work towards supporting Rest Assured. Pointers to how to get started with this will be helpful.

Though request class and response is the same, the field description may be different. One example is create request.

POST /user

the request user class don't need to provide a id field, and in the response user class, I need to document that the id is generated by the server.

How can I archive this?

Not sure if this si the best place to ask this but have been stuck on setting up auto rest docs on one of my projects. The issue comes from dependencies from an external jar (models) and the mockmvc mapping when returning from the service. As a side note, not sure this is relevant, but it tries to pull in all objects related to that test. Included one below (of 15). Not sure if this is a mem error, rest docs, auto rest docs, or doclet issue. Don't mind doing a pull if someone points me in the right direction.

[capital.scalable.restdocs.javadoc.JavadocReader] WARN - No Javadoc found for class com.refund.model.request.RefundRequest

java.lang.StackOverflowError at java.util.regex.Pattern$Slice.match(Pattern.java:3972) at java.util.regex.Pattern$CharProperty.match(Pattern.java:3777) at java.util.regex.Pattern$Slice.match(Pattern.java:3972) at java.util.regex.Pattern$CharProperty.match(Pattern.java:3777) at java.util.regex.Pattern$Slice.match(Pattern.java:3972) at java.util.regex.Pattern$CharProperty.match(Pattern.java:3777) at java.util.regex.Pattern$Slice.match(Pattern.java:3972) at java.util.regex.Pattern$CharProperty.match(Pattern.java:3777) at java.util.regex.Pattern$Slice.match(Pattern.java:3972) at java.util.regex.Pattern$Start.match(Pattern.java:3461) at java.util.regex.Matcher.search(Matcher.java:1248) at java.util.regex.Matcher.find(Matcher.java:637) at java.util.regex.Matcher.replaceAll(Matcher.java:951) at java.lang.String.replaceAll(String.java:2223) at capital.scalable.restdocs.javadoc.JavadocReaderImpl.classToRelativePath(JavadocReaderImpl.java:94) at capital.scalable.restdocs.javadoc.JavadocReaderImpl.classJavadoc(JavadocReaderImpl.java:80) at capital.scalable.restdocs.javadoc.JavadocReaderImpl.resolveFieldComment(JavadocReaderImpl.java:64) at capital.scalable.restdocs.jackson.FieldDocumentationVisitorContext.resolveComment(FieldDocumentationVisitorContext.java:68) at capital.scalable.restdocs.jackson.FieldDocumentationVisitorContext.addField(FieldDocumentationVisitorContext.java:53) at capital.scalable.restdocs.jackson.FieldDocumentationVisitorWrapper.addFieldIfPresent(FieldDocumentationVisitorWrapper.java:138) at capital.scalable.restdocs.jackson.FieldDocumentationVisitorWrapper.expectIntegerFormat(FieldDocumentationVisitorWrapper.java:104) at com.fasterxml.jackson.databind.ser.std.StdSerializer.visitIntFormat(StdSerializer.java:215) at com.fasterxml.jackson.databind.ser.std.NumberSerializers$Base.acceptJsonFormatVisitor(NumberSerializers.java:75) at com.fasterxml.jackson.databind.ser.std.NumberSerializers$IntegerSerializer.acceptJsonFormatVisitor(NumberSerializers.java:128) at capital.scalable.restdocs.jackson.FieldDocumentationObjectVisitor.optionalProperty(FieldDocumentationObjectVisitor.java:66) at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.depositSchemaProperty(BeanPropertyWriter.java:816) at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.acceptJsonFormatVisitor(BeanSerializerBase.java:833) at capital.scalable.restdocs.jackson.FieldDocumentationArrayVisitor.itemsFormat(FieldDocumentationArrayVisitor.java:44) at com.fasterxml.jackson.databind.ser.std.StdSerializer.visitArrayFormat(StdSerializer.java:277) at com.fasterxml.jackson.databind.ser.std.AsArraySerializerBase.acceptJsonFormatVisitor(AsArraySerializerBase.java:302) at capital.scalable.restdocs.jackson.FieldDocumentationObjectVisitor.optionalProperty(FieldDocumentationObjectVisitor.java:66) at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.depositSchemaProperty(BeanPropertyWriter.java:816) at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.acceptJsonFormatVisitor(BeanSerializerBase.java:833) at capital.scalable.restdocs.jackson.FieldDocumentationObjectVisitor.optionalProperty(FieldDocumentationObjectVisitor.java:66) at com.fasterxml.jackson.databind.ser.BeanPropertyWriter.depositSchemaProperty(BeanPropertyWriter.java:816) at com.fasterxml.jackson.databind.ser.std.BeanSerializerBase.acceptJsonFormatVisitor(BeanSerializerBase.java:833) at capital.scalable.restdocs.jackson.FieldDocumentationObjectVisitor.optionalProperty(FieldDocumentationObjectVisitor.java:66)

Hi,

first thanks for your good work :)

I've this case

@RequestMapping(method = POST, value = "/bulk")
public ResponseBulkImport bulkImport(
	@RequestBody final String bulkImport)
{
	return service.doSomeWork(bulkImport);
}

I need to have the raw json to make some special controls so i can't use a bean.
But in my documentation, i want to explain all the fields my API can accept.

So in my test, it would be great if i could do something like that :

String bulkImport = new ObjectMapper().writeValueAsString(buildBulkImport());
mockMvc.perform(post("/classified/bulk")
		.with(documentRequestBodyAs(BulkImport.class))
		.contentType(APPLICATION_JSON_UTF8)
		.content(bulkImport))

Look at the documentBodyAs() method who is a RequestPostProcessor

I've found that i need to modify the JacksonRequestFieldSnippet classe and particulary the method Type getType(HandlerMethod method)

But i don't know how to get the information BulkImport.class

An other solution is to have something like that :

@RequestMapping(method = POST, value = "/bulk")
public ReponsesBulkImport bulkImport(
        @DocumentRequestBodyAs(BulkImport.class)
        @RequestBody final String bulkImport)
{
		return service.doSomeWork(bulkImport);
}

It's more easy to extract the information BulkImport.class, but i don't know

• if I a can use a standard annotation in Java
• use a Jackson annotation
• or write my own annotation but where to put it

It would be a pleasure to provide a PR, but i need some help to go in the good direction :)

Thanks

(sorry for my bad english)

Let's say we have an interface:

public interface MyInterface {

    /**
    * My comment for the name;
    */
    String getName();
}

And an implementation;

public class MyImplementation implements MyInteface {

    private String name;
   
    @Override
    public String getName() {
        return name;
    }
}

I would expect that the documentation for the name to be picked up from the Javadoc of the MyInterface. If there is a comment on the overridden methods than that one needs to be taken.

As a bonus the the Javadoc inheritDoc could be used as well (but this is not that important to me).

I am using a build of the version 1.0.10-SNAPSHOT since a few weeks. I tried the new 1.0.10 release but I get errors like :

2017-11-03 15:24:46.777 ERROR 33692 --- [           main] c.s.restdocs.javadoc.JavadocReader       : Failed to read file WebhookEndpointController.json

com.fasterxml.jackson.databind.JsonMappingException: Can not construct instance of capital.scalable.restdocs.javadoc.ClassJavadoc$FieldJavadoc: no String-argument constructor/factory method to deserialize from String value ('')
 at [Source:<filePath>/WebhookEndpointController.json; line: 1, column: 53] (through reference chain: capital.scalable.restdocs.javadoc.ClassJavadoc["fields"]->java.util.LinkedHashMap["webhookEndpointRepository"])
        at com.fasterxml.jackson.databind.JsonMappingException.from(JsonMappingException.java:270) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.DeserializationContext.instantiationException(DeserializationContext.java:1456) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.DeserializationContext.handleMissingInstantiator(DeserializationContext.java:1012) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.ValueInstantiator._createFromStringFallbacks(ValueInstantiator.java:370) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.std.StdValueInstantiator.createFromString(StdValueInstantiator.java:315) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.BeanDeserializerBase.deserializeFromString(BeanDeserializerBase.java:1283) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.BeanDeserializer._deserializeOther(BeanDeserializer.java:159) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.BeanDeserializer.deserialize(BeanDeserializer.java:150) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.std.MapDeserializer._readAndBindStringKeyMap(MapDeserializer.java:517) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.std.MapDeserializer.deserialize(MapDeserializer.java:362) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.std.MapDeserializer.deserialize(MapDeserializer.java:27) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.SettableBeanProperty.deserialize(SettableBeanProperty.java:504) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.impl.FieldProperty.deserializeAndSet(FieldProperty.java:111) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.BeanDeserializer.vanillaDeserialize(BeanDeserializer.java:276) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.deser.BeanDeserializer.deserialize(BeanDeserializer.java:140) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.ObjectReader._bindAndClose(ObjectReader.java:1626) ~[jackson-databind-2.8.9.jar:2.8.9]
        at com.fasterxml.jackson.databind.ObjectReader.readValue(ObjectReader.java:1266) ~[jackson-databind-2.8.9.jar:2.8.9]
        at capital.scalable.restdocs.javadoc.JavadocReaderImpl.readJson(JavadocReaderImpl.java:164) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.javadoc.JavadocReaderImpl.readFiles(JavadocReaderImpl.java:145) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.javadoc.JavadocReaderImpl.classJavadoc(JavadocReaderImpl.java:122) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.javadoc.JavadocReaderImpl.resolveCommentFromClassHierarchy(JavadocReaderImpl.java:224) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.javadoc.JavadocReaderImpl.resolveMethodComment(JavadocReaderImpl.java:86) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.misc.DescriptionSnippet.resolveComment(DescriptionSnippet.java:74) [spring-auto-restdocs-core-1.0.10.jar:na]
        at capital.scalable.restdocs.misc.DescriptionSnippet.createModel(DescriptionSnippet.java:52) [spring-auto-restdocs-core-1.0.10.jar:na]
        at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:64) [spring-restdocs-core-1.1.3.RELEASE.jar:na]
        at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:196) [spring-restdocs-core-1.1.3.RELEASE.jar:na]
        at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55) [spring-restdocs-mockmvc-1.1.3.RELEASE.jar:na]
        at org.springframework.test.web.servlet.MockMvc.applyDefaultResultActions(MockMvc.java:195) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.springframework.test.web.servlet.MockMvc.perform(MockMvc.java:163) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at com.ikentoo.irene.controller.rest.WebhookEndpointControllerTest.registerWebhookEndpoint(WebhookEndpointControllerTest.java:49) [test-classes/:na]
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_144]
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_144]
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_144]
        at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_144]
        at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50) [junit-4.12.jar:4.12]
        at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12) [junit-4.12.jar:4.12]
        at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47) [junit-4.12.jar:4.12]
        at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17) [junit-4.12.jar:4.12]
        at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26) [junit-4.12.jar:4.12]
        at org.springframework.test.context.junit4.statements.RunBeforeTestMethodCallbacks.evaluate(RunBeforeTestMethodCallbacks.java:75) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.springframework.test.context.junit4.statements.RunAfterTestMethodCallbacks.evaluate(RunAfterTestMethodCallbacks.java:86) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.springframework.restdocs.JUnitRestDocumentation$1.evaluate(JUnitRestDocumentation.java:55) [spring-restdocs-core-1.1.3.RELEASE.jar:na]
        at org.junit.rules.RunRules.evaluate(RunRules.java:20) [junit-4.12.jar:4.12]
        at org.springframework.test.context.junit4.statements.SpringRepeat.evaluate(SpringRepeat.java:84) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325) [junit-4.12.jar:4.12]
        at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:252) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:94) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290) [junit-4.12.jar:4.12]
        at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71) [junit-4.12.jar:4.12]
        at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288) [junit-4.12.jar:4.12]
        at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58) [junit-4.12.jar:4.12]
        at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268) [junit-4.12.jar:4.12]
        at org.springframework.test.context.junit4.statements.RunBeforeTestClassCallbacks.evaluate(RunBeforeTestClassCallbacks.java:61) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.springframework.test.context.junit4.statements.RunAfterTestClassCallbacks.evaluate(RunAfterTestClassCallbacks.java:70) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.junit.runners.ParentRunner.run(ParentRunner.java:363) [junit-4.12.jar:4.12]
        at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.run(SpringJUnit4ClassRunner.java:191) [spring-test-4.3.10.RELEASE.jar:4.3.10.RELEASE]
        at org.apache.maven.surefire.junit4.JUnit4Provider.execute(JUnit4Provider.java:283) [surefire-junit4-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.junit4.JUnit4Provider.executeWithRerun(JUnit4Provider.java:173) [surefire-junit4-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:153) [surefire-junit4-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:128) [surefire-junit4-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.booter.ForkedBooter.invokeProviderInSameClassLoader(ForkedBooter.java:203) [surefire-booter-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.booter.ForkedBooter.runSuitesInProcess(ForkedBooter.java:155) [surefire-booter-2.18.1.jar:2.18.1]
        at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:103) [surefire-booter-2.18.1.jar:2.18.1]

With the SNAPSHOT version, I have no problem

Hi!
When I first time heard about spring rest doc, I thought it would be ideal to generate content from javadocs. At first I was a little bit disappointed when I understood how it works, but then I found your library. This is the right approach to generate documentation, because I have documended my code via Kdoc(javadoc extension) - https://kotlinlang.org/docs/reference/kotlin-doc.html
Now I want try it, but can you say, can it work with kotlin?

Subj.

Hello,

It would be nice to have the possibility to translate the snippets header without creating a custom snippet and overriding the getHeader() method.

I don't know the best way to achieve this, but I thought about configuring the snippets headers on "MockMvcBase" like class.

Happens when calling invalid endpoint from the test.

I'm having trouble to write my documentation in Portuguese because the titles are generated using the method name and the code is all Engish (thank god!).

I think it should be nice to overwrite the section title from javadoc and let the lib use the method name as default. For example:

/**
 * Create an internal user
 *
 * @title Criar usuário interno
 */
@ResponseStatus(HttpStatus.CREATED)
@RequestMapping(path = "/v1/users", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
UserResponse create(@Valid @RequestBody CreateUserDTO createUserDTO) {
  ...
}

And the section title will be Criar usuário interno instead of create.

If the @title is not provided, then the section title will still the default behavior of using method name.

The second suggestion is to make possible to change de default templates location, so we can provide an own template snippet and translate the table's header.
For example, make possible to translate the request-fields snippets:

{{#hasContent}}|===
|Caminho|Tipo|Opcional|Descrição

{{#content}}
|{{path}}
|{{type}}
|{{optional}}
|{{description}}

{{/content}}
|==={{/hasContent}}{{#noContent}}No request body.{{/noContent}}

Are you planning to add links support? Currently, information about links goes to "Response fields" section.

Hi! My problem is generating the WireMock stub using the step up in the documentation.

When I create a set up custom the stub aren't created and when I use the default MockMvc configuration works.

 @fbenz 
 public void setUp() {
        this.mockMvc = MockMvcBuilders
                .webAppContextSetup(context)
                .alwaysDo(prepareJackson(objectMapper))
                .alwaysDo(document("{class-name}/{method-name}",
                                   preprocessRequest(), commonResponsePreprocessor()))
                .apply(documentationConfiguration(restDocumentation)
                               .uris()
                               .and().snippets()
                               .withDefaults(curlRequest(), httpRequest(), httpResponse(),
                                             requestFields(), responseFields(), pathParameters(),
                                             requestParameters(), description(), methodAndPath(),
                                             section()))
                .build();
}

 @Test
  public void getTemplate() throws Exception {
    this.mockMvc.perform(get("/")
                                 .contentType(MediaType.APPLICATION_JSON)
                                 .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("result", is("success")))
            .andExpect(jsonPath("version", is("0.0.1")))
            .andDo(WireMockRestDocs.verify().stub("getFlapTemplate"))
            .andDo(MockMvcRestDocumentation.document("getFlapTemplate", SpringCloudContractRestDocs.dslContract()));
}

Is it possible to generate the WireMock stub with a custom's configuration?

Thanks in advance! :)

I have a project where we actually do not use hibernate validator. The dependency is being pulled automatically by auto-restdocs which means that it is failing as I don't have implementation of the el-api in my dependencies.

I would propose that you make the hibernate-validator a provided dependency and only instantiate the ConstraintReaderImpl if hibernate is present, or even make it so that you can configure the JacksonPreparingResultHandler.

It would be nice to be able to specify alternate responses for expected error codes. For example:

@RequestMapping(value = "/login", method = POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @ResponseStatus(HttpStatus.CREATED)
    @ResponseBody
    public ResponseEntity<LoginResponse> login(@RequestParam String username, @RequestParam String password)

There may be other expected errors that do not have that field structure, or are a different class altogether and would return a different response code; for example, a 403 Forbidden or 404 Not Found for a bad authorization attempt, or a 500 for an unknown error. Is there any provision for such alternate codes and response bodies, or do they need to be placed in the asciidoc directly?

For example I have a model with id that is generated on the server. When a new model is POSTed there shouldn't be any id in it and I can configure ObjectMapper to skip null fields so that id is hidden in "Example request" section, but having it described in the "Request structure" section could be confusing for the reader.

Subj. Example of code:
@GetMapping("/classes")
List searchClasses(@validated @ModelAttribute SearchClassesRequest searchClassesRequest) {
return groupXClassBriefService.searchClasses(searchClassesRequest);
}
Please help.

There is an issue with the Doclet and how that Doclet and JavaDoc are called from within Gradle.

From my research is understand that Gradle is passing default values from various flags. One of those flags if for example the "-d" flag.

Due to the Doclet and it not supporting those flags that Gradle passes the build process always fails with the following error. It may possible that there are other flags that have to be checked as well.

javadoc: error - invalid flag: -d

I would appreciate a fix for the doclet.

The base parent of all Scala collection classes is scala.collection.Traversable.
Please handle it in the same way you handle Java List.

Mark somehow endpoint as deprecated in documentation

With Spring it is possible to use normal POJOs to substitute multiple @PathVariable or @RequestParam.

This blog post displays how it can be used.

I think it would be great if you can support something like this. I think that the JacksonRequestFieldSnippet can be somehow used to achieve this.

I think that the only thing is how to know which parameters you should use for mapping. For this I would propose that you allow creating the snippet with some custom annotation. If a parameter has that annotation then you can get that type and do the the same that what you are doing with the JacksonRequestFieldSnippet. Making the annotation customizable you will allow the users to define their own and they won't need to pull in spring-auto-restdocs into production.

Expected behaviour

Actual behaviour

Example code:

LyashenkoGS@6a6e7b4

Spring REST Docs offers @AutoConfigureRestDocs to simplify the setup. If possible, we should provide @AutoConfigureAutoRestDocs.

When I use explicit types extending generic types for @ResponseBody, only fields from parent generic types are discovered and added to a response documentation, specific type fields are not picked up.
Is it me doing something wrong, or there is no support for generic types in general so far?
Thanks!

Add a test to the example project that uses Spring REST Docs to show that Spring Auto REST Docs is just an extension and can be used whenever it fits and one can fallback the original.

Two cases here.

1. For example, I don't use AuthorizationSnippet at all, but Authorization section is still generated and gives an error since authorization.adoc is missing.

2. I use RequestParametersSnippet and add it to MockMvc defaults, but in fact there are only a couple of methods that have request parameters. Currently "Query parameters" section is generated for each resource and just takes place in the documentation.

I am getting the following error:

Error:(66, 0) Could not find capital.scalable:spring-auto-restdocs-json-doclet:1.0.6-SNAPSHOT.
Required by:
    capital.scalable:spring-auto-restdocs-example:1.0.6-SNAPSHOT

Am I missing something here?

Regards

New repo name: spring-auto-restdocs

Renaming of an existing GitHub repo is possible: https://help.github.com/articles/renaming-a-repository/

We can also think of moving json-doclet to a separate repo, but that's not required.

Hi, first of all thanks for the great tool.
I have issue with the field documentation annotated with @see :

/**
 *
*  @see <a href="https://github.com/jirutka/rsql-parser">this for the syntax</a>
*/
    private String rsqlFilter;

The description is being rendered literally as
See <a href="https://github.com/jirutka/rsql-parser">this for the syntax</a>.
i.e. the < and > characters are escaped, causing the text to be rendered as-is and not as HTML tags.
Please do not escape the HTML entities where applicable.
Thanks

Subj

Ideas so far:

• REST Docs Jackson
• Auto REST Docs
• Lazy REST Docs
• Robo REST Docs
• Slack REST Docs

We need a name before we can register a Maven artifact.

Hi,

SpringRestDocs provide the capacity to fail test when fields are undocumented.

Extract from thé documentation :

"When documenting fields, the test will fail if an undocumented field is found in the payload. Similarly, the test will also fail if a documented field is not found in the payload and the field has not been marked as optional"

Does SpringAutoRestDocs provides the same capacity when javadoc is missing ?

Thanks for your work.

i tried to apply this plugin to a project where the resources are in one project (A) and the domain-classes are in another project (B).

restdoc-tests are in A, so javadoc is only read for these classes. Is it possible to generate the stuff that goes into generated-javadoc-json for project B and have spring-auto-restdoc pick up generated-javadoc-json for both A and B?

Hello,

First, thank you for this awesome tool.

Can you standardize the way arrays and collections are rendered in the request and the response ?

Is this example, categories in the request and the response are Array of String.

Here the code used to generate this documentation :
spring-auto-restdocs-example.zip

Subj.

related to #119

• RequestParam
• anything else?

Hi All,

What would be the correct way to deal with a field of type OffsetDateTime

Currently it is being completely enumerated which I dont want.

`

Kind thanks,
Serge

@PutMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void createOrUpdate(
        @PathVariable long id,
        @RequestBody Video video,
        @RequestParam(defaultValue = "true") boolean create) {
}

result in

Parameter | Type | Optional | Description
create | boolean | false | 

Actually, create is optional with default value set. Also it will be nice to add default value to the request parameter snippet