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
How it works
All recoded Spring REST docs tests are located in the folder
This signals the plugin to enable the Spring REST docs functionality.
It looks relative to the
target/generated-snippets or relative to
Once the plugin detects Spring REST Docs it
snippetsattribute to the generated snippets-folder, therefore, includes like this work.
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 names auto-complete when using Ctrl+Space. Press Ctrl+B to navigate to the folder.
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.