This talk introduces Spring Auto REST Docs, an extension to Spring REST Docs that helps you write less and get more. We have been using and evolving our Spring REST Docs extension for over 1.5 years and recently open sourced it: https://github.com/ScaCap/spring-auto-restdocs Spring Auto REST Docs uses tests, introspection and Javadoc to automatically document request and response parameters. We will look at how much work this saved and how it increased the quality of our documentation. Sprint Auto REST Docs proposes a tight coupling of code and documentation. This way we make it easy to add documentation in the first place, and to keep it up to date as your platform evolves. During the presentation, we give instructions on how to use the extension and discuss pros and cons of the proposed approach. We will present our own system as a real-life implementation and highlight the benefits of reusing tests, bean validation and Javadoc together with the freedom of AsciiDoc to generate documentation.
For further reading: https://dzone.com/articles/introducing-spring-auto-rest-docs
Project documentation: https://scacap.github.io/spring-auto-restdocs/
Project: https://github.com/ScaCap/spring-auto-restdocs
4. @spring_io
#springio17
Scalable Capital
• Europe’s fastest growing Digital Wealth Manager
• Authorized financial institute in Germany and the UK
• From scratch with Spring Boot
• Joined effort with Juraj Misur @juraj_misur
20. @spring_io
#springio17
AsciiDoc
[[resources-weather]]
= Weather for your city
`POST /weather`
Up-to-date temperature for the given city
== Response structure
include::{snippets}/weather/response-fields.adoc[]
== Example request/response
include::{snippets}/weather/curl-request.adoc[]
include::{snippets}/weather/http-response.adoc[]
29. @spring_io
#springio17
Spring Auto REST Docs
@Test
public void shouldReturnWeatherForBarcelona() throws Exception {
mockMvc.perform(
post("/weather")
.contentType(MediaType.APPLICATION_JSON)
.content("{"country": "ES", "city": "Barcelona"}")
)
.andExpect(status().isOk())
.andExpect(jsonPath("$.temperature", is(20)));
.andDo(document("weather"));
}
30. @spring_io
#springio17
Javadoc
class WeatherRequest {
/**
* Country code.
*/
private String country;
/**
* City name.
*/
private String city;
}
Path Type Optional Description
country String true Country code.
city String true City name.
31. @spring_io
#springio17
Constraints
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
@IsoCountryCode
private String country;
/**
* City name.
*/
@NotBlank
private String city;
}
Path Type Optional Description
country String false Country code.
Must be an ISO country code.
city String false City name.
33. @spring_io
#springio17
Constraints
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
@IsoCountryCode(groups = Iso.class)
@CountryName(groups = Plain.class)
private String country;
}
Path Type Optional Description
country String false Country code.
ISO: Must be an ISO country code.
Plain: Must be a country name.
34. @spring_io
#springio17
Enums
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
private Country country;
/**
* City name.
*/
@NotBlank
private String city;
}
Path Type Optional Description
country String false Country code.
Must be one of [DE, ES, FR, PT, US].
city String false City name.
36. @spring_io
#springio17
Extension: Javadoc on method
/**
* Up-to-date weather data for cities around the globe.
*/
@PostMapping("weather")
public WeatherResponse weather(
@RequestBody @Valid WeatherRequest weatherRequest) {
return new WeatherResponse(20);
}
2.8. Weather
POST /weather
Up-to-date weather data for cities around the globe.
38. @spring_io
#springio17
Extension: Path Parameters
/**
* Up-to-date weather data for cities around the globe.
*
* @param country Country code.
* @param city City name.
*/
@GetMapping("weather/{country}/{city}")
public WeatherResponse weatherPath(
@PathVariable @IsoCountryCode String country,
@PathVariable String city) {
return new WeatherResponse(20);
}
42. @spring_io
#springio17
Extension: Query Parameters
/**
* Up-to-date weather data for cities around the globe.
*
* @param country Country code.
* @param city City name.
*/
@GetMapping("weatherParam")
public WeatherResponse weatherParam(
@RequestParam @IsoCountryCode String country,
@RequestParam String city) {
return new WeatherResponse(20);
}
45. @spring_io
#springio17
Section Snippet
[[resources-weather]]
=== Weather for your city
`POST /weather`
Up-to-date temperature for the given city
===== Request structure
include::{snippets}/weather/request-fields.adoc[]
===== Response structure
include::{snippets}/weather/response-fields.adoc[]
===== Example request/response
include::{snippets}/weather/curl-request.adoc[]
include::{snippets}/weather/http-response.adoc[]
include::{snippets}/weather/section.adoc[]
Documentation path
Spring MVC Controller
Javadoc
Method name