Introducing Spring Auto REST Docs - Spring IO 2017

Introducing
Spring Auto REST Docs
Florian Benz
@flbenz

@spring_io
#springio17
DR REST DOCS
OR: HOW I LEARNED TO STOP WORRYING
AND LOVE DOCUMENTATION

@spring_io
#springio17
Florian Benz
Software Engineer
@flbenz

@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

@spring_io
#springio17
Scalable Capital
founded
Dec 2014
Proof of concept
Jul 2015
First article
Nov 2015

@spring_io
#springio17
Open source
&
First release
Dec 2016
DZone article
Jan 2017
Two releases
with fixes and
features
Feb & Mar 2017

@spring_io
#springio17
Our Story

@spring_io
#springio17
Manual Documentation
DocumentationCode

@spring_io
#springio17
A single big document

@spring_io
#springio17
Specification-Driven
Documentation
DocumentationCode
Specification

@spring_io
#springio17
RAML Specification
/weather:
get:
queryParameters:
city:
description: Name of a city in the given country.
responses:
200:
body:
application/json:
schema: |
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "Weather information",
"properties": {
"temperature": { "type": "number" }
}
}

@spring_io
#springio17
Swagger / OpenAPI
@GetMapping("weatherParam")
@ApiOperation("weather")
@ApiImplicitParams({
@ApiImplicitParam(name = "country", value = "Country code", required = true,
dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "city", value = "City", required = true,
dataType = "string", paramType = "query")
})
@ApiResponses({
@ApiResponse(code = 200, message = "Success", response =
WeatherResponse.class)
})
public WeatherResponse weatherParam(@RequestParam @IsoCountryCode String
country,
@RequestParam String city) {
return new WeatherResponse(20);
}

@spring_io
#springio17
Swagger / OpenAPI

@spring_io
#springio17
Postman

@spring_io
#springio17
Test-Driven Documentation
DocumentationCode
Tests

@spring_io
#springio17
Spring REST Docs
Generated
snippets
Tests
Hand-written
documentation
Documentation

@spring_io
#springio17
Spring MVC Test
@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)));
}

@spring_io
#springio17
Spring REST Docs
@Test
mockMvc.perform(
post("/weather")
)
.andDo(document("weather",
requestFields(
fieldWithPath("country").description("Country code"),
fieldWithPath("city").description("City name"))));
}

@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[]

@spring_io
#springio17
Spring REST Docs

@spring_io
#springio17
Spring REST Docs
Controller
POJO
Response Entity
Jackson
HTTP response Documented

@spring_io
#springio17
Extending
Spring REST Docs

@spring_io
#springio17
Motivation
requestFields(
fieldWithPath("country").description("Country code"),
fieldWithPath("city").description("Name of a city"))));
We are lazy

@spring_io
#springio17
Proof of concept

@spring_io
#springio17
Controller
POJO
Response Entity
Jackson
HTTP response
Javadoc
Introspection

@spring_io
#springio17
Spring REST Docs
@Test
mockMvc.perform(
post("/weather")
)
requestFields(
fieldWithPath("country").optional().description("Country code"),
fieldWithPath("city").optional().description("City name"))));
}

@spring_io
#springio17
@Test
mockMvc.perform(
post("/weather")
)
.andDo(document("weather"));
}

@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.

@spring_io
#springio17
Constraints
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
@IsoCountryCode
/**
* City name.
*/
@NotBlank
}
country String false Country code.
Must be an ISO country code.
city String false City name.

@spring_io
#springio17
Constraints
package.OneOf.description=Must be one of ${value}
package.IsoCountryCode.description=Must be an ISO country code
ConstraintDesciptions.properties

@spring_io
#springio17
Constraints
/**
*/
@NotNull
@IsoCountryCode(groups = Iso.class)
@CountryName(groups = Plain.class)
}
ISO: Must be an ISO country code.
Plain: Must be a country name.

@spring_io
#springio17
Enums
/**
*/
@NotNull
private Country country;
/**
* City name.
*/
@NotBlank
}
Must be one of [DE, ES, FR, PT, US].
city String false City name.

@spring_io
#springio17
Original: hand-written
2.8. Weather
POST /weather
Up-to-date weather data for cities around the globe.
= Weather for your city
`POST /weather`

@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) {
}
2.8. Weather
POST /weather
Up-to-date weather data for cities around the globe.

@spring_io
#springio17
Original: Path Parameters
pathParameters(
parameterWithName("country").description("Country code"),
parameterWithName("city").description("City name"))));

@spring_io
#springio17
Extension: Path Parameters
/**
*
* @param country Country code.
* @param city City name.
*/
@GetMapping("weather/{country}/{city}")
public WeatherResponse weatherPath(
@PathVariable @IsoCountryCode String country,
@PathVariable String city) {
}

@spring_io
#springio17
Path Parameters

@spring_io
#springio17
Original: Query Parameters
requestParameters(
parameterWithName("country").description("Country code"),
parameterWithName("city").description("City name"))));

@spring_io
#springio17
Extension: Query Parameters
/**
*
* @param country Country code.
* @param city City name.
*/
@GetMapping("weatherParam")
public WeatherResponse weatherParam(
@RequestParam @IsoCountryCode String country,
@RequestParam String city) {
}

@spring_io
#springio17
Query Parameters

@spring_io
#springio17
Section Snippet
=== Weather for your city
`POST /weather`
===== 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

@spring_io
#springio17
Authorization snippet

@spring_io
#springio17
Content Modifiers
[
1,
2,
3,
4,
5
]
[
1,
2,
3
]
array shortener

@spring_io
#springio17
Content Modifiers
%PDF-1.5
%��
12 0 obj
<<
/Length 3654
/Filter /FlateDecode
>>
<binary>
binary replacement

@spring_io
#springio17
Benefits
Less to write
Code review Maintainability
Happier developers
DRY
Accurate

@spring_io
#springio17
Sounds good!
Issues?

@spring_io
#springio17
It’s an extension
Authorization snippet
Javadoc/introspection snippets
Content modifiers

@spring_io
#springio17
at Scalable Capital

@spring_io
#springio17
Thank you

@spring_io
#springio17
Q&A
@flbenz

Introducing Spring Auto REST Docs - Spring IO 2017

More Related Content

What's hot

Recently uploaded

Introducing Spring Auto REST Docs - Spring IO 2017