Spring REST Docs
Spring REST Docs allow the developer to write API documentation using information recorded in test cases. The plugin supports the operation::[]-macro of Spring REST Docs in the editor and the preview.
| This requires version 0.30.6+ of the plugin. |
What Spring REST Docs provides
Spring REST Docs allow the developer to write API documentation using information recorded in test cases. These ensure that the examples in the documentation work with the current version of the code.
When running the tests, Spring REST Docs creates a folder generated-snippets with the recorded examples.
The developer can reference these snippets in the documentation.
What the AsciiDoc plugin provides
This plugin supports developers when documenting their Spring REST Docs. It provides auto-complete for the editor and renders a preview that shows the documentation content together with the recorded examples of the tests.
As the editor support requires the generated-snippets folder to be present, users need to run their tests to create and populate it before the editor support activates.
|
How it works
All recoded Spring REST docs tests are located in the folder generated-snippets.
This signals the plugin to enable the Spring REST docs functionality.
It looks relative to the pom.xml for target/generated-snippets or relative to build.gradle or build.gradle.kts for build/generated-snippets.
Once the plugin detects Spring REST Docs it
-
Sets the
snippetsattribute to the generated snippets-folder, therefore, includes like this work.include::{snippets}/headers-example/response-headers.adoc[]File names auto-complete when using Ctrl+Space. Press Ctrl+B to navigate to the folder or file.
-
Activates the operation:xxx[] macro, therefore the following works:
operation::index-example[snippets='response-fields,http-response,links']Operation names auto-complete when using Ctrl+Space. Press Ctrl+B to navigate to the folder.
Example project
The Spring REST Docs project provides an example project how to set up things: https://github.com/spring-projects/spring-restdocs-samples/tree/main/restful-notes-spring-hateoas
As the editor support requires the generated snippets-folder to be present, users need to run their tests to create and populate it before the editor support activates.