My talk on JEEConf about Spring Rest Docs, Swagger and Test Driven Documentation. Material covers: 1. Swagger. SpringFox 2. Swagger approaches and trade-offs 3. Test Driven Development → Test Driven Documentation 4. Live Coding session - how to connect and start using SpringRestDocs 5. Spring Rest Docs features 6. AsciiDoc is awesome (syntax, examples, extensions). 7. Migration of your project from Swagger to SpringRestDocs

1. Test Driven
Documentation
with Spring Rest Docs
Tsypuk Roman
@tsypuk_r
tsypuk.conf@gmail.com

2. About me
• Sr Software engineer at Lohika, Altran Group
• G4 organizer of Lohika Java Community
• java8, spring, spring boot, microservices, security
• radio HAM, software defined radio
2

3. Agenda
• Age of Swagger
• Test Driven Documentation
• Spring Rest Docs under the hood
• Migration from Swagger to Spring Rest Docs
3

4. Age of Swagger
4IMG http://swagger.io

5. Demo
https://github.com/tsypuk/springrestdoc 5

6. URI-based documentation
6

7. @GetMapping(path = "/speakers/{id}")
public ResponseEntity<SpeakerResource> getSpeaker(@PathVariablelong id) {
return speakerRepository.findOne(id)
.map(speaker -> ResponseEntity.ok(new SpeakerResource(speaker)))
.orElse(new ResponseEntity(HttpStatus.NOT_FOUND));
}
RestController
7

8. @GetMapping(path = "/speakers/{id}")
public ResponseEntity<SpeakerResource> getSpeaker(@PathVariablelong id) {
return speakerRepository.findOne(id)
.map(speaker -> ResponseEntity.ok(new SpeakerResource(speaker)))
.orElse(new ResponseEntity(HttpStatus.NOT_FOUND));
}
RestController
1
2
3
4
5
6
8

9. @ApiOperation(
value = "Find speaker by ID",
notes = "For valid response try integer IDs with value 1 ... 999.",
response = SpeakerResource.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successful retrieve the speaker.", response = SpeakerResource.class),
@ApiResponse(code = 400, message = "Invalid ID supplied"),
@ApiResponse(code = 404, message = "Speaker not found"),
@ApiResponse(code = 500, message = "Internal server error.")})
@GetMapping(value = "/{id}")
public ResponseEntity<SpeakerResource> getSpeaker(
@ApiParam(value = "ID of speaker that needs to be fetched",
allowableValues = "range[1,999]",
required = true)
@PathVariable long id) {
return speakerRepository.findOne(id)
.map(speaker -> ResponseEntity.ok(new SpeakerResource(speaker)))
.orElse(new ResponseEntity(HttpStatus.NOT_FOUND));
}
Swagger Documented Controller
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 10

10. Swagger Documented Models
1
2
3
4
5
6
7
8
…
@ApiModel(value = "Speaker Resource",
description = "Speaker detailed description.")
public class SpeakerResource extends ResourceSupport {
@ApiModelProperty(value = "Name of the Speaker in full format.",
example = "Roman Tsypuk",
dataType = "java.lang.String",
required = true)
private String name;
11

11. /speakers/{speakerId}:
put:
tags:
- speaker
summary: Updates a speaker with new data
description: ""
operationId: updateSpeaker
consumes:
- application/json
produces:
- application/json
parameters:
- in: path
name: speakerId
description: ID of speaker that needs to be updated
required: true
type: string
- in: jsonData
name: name
description: Updated name of the speaker
required: true
type: string
- in: jsonData
name: company
description: Updated company of the speaker
required: false
type: string
responses:
"405":
description: Validation exception
"404":
description: Speaker not found
"400":
description: Invalid ID supplied
"201":
description: successful operation
schema:
type: array
items:
$ref: "#/definitions/Speaker"
security:
- service_auth:
- write_speakers
- read_speakers
definitions
Speaker:
description: Speaker resource
required:
- name
- photoUrls
properties:
id:
type: integer
format: int64
topics:
type: array
items:
$ref: "#/definitions/Topic"
name:
type: string
example: Josh Long
company:
type: string
example: Pivotal
status:
type: string
description: I love Spring
Swagger specification yaml file
12

12. Bottom-up (code-first)
io.swagger.annotations
Top-down (contract-first)
swagger.(yaml/json)
Tightly coupled code
with annotations
Swagger Approaches
13

13. Hypermedia Support
13

14. Level 0: XML RPC/Remoting
Singular service endpoint for everything
Level 1:
Multiple resources
Level 2:
Proper use of HTTP verbs
Level 3 HATEOAS:
Discoverability, Hypermedia controls
Swagger 2.0
https://martinfowler.com/articles/richardsonMaturityModel.html
Richardson Maturity Model
14

15. Level 0: XML RPC/Remoting
Singular service endpoint for everything
Level 1:
Multiple resources
Level 2:
Proper use of HTTP verbs
Level 3 HATEOAS:
Discoverability, Hypermedia controls
Swagger 2.0
Hypermedia is not supported in swagger 2.0
15

16. Level 0: XML RPC/Remoting
Singular service endpoint for everything
Level 1:
Multiple resources
Level 2:
Proper use of HTTP verbs
Level 3 HATEOAS:
Discoverability, Hypermedia controls
Swagger 2.0
OpenAPI3.0
OpenAPI 3.0 is comming
16

17. • Depends on the framework implementation details
• Specification is only machine-readable
• The format is not easy to use
• HATEOAS links are not supported (swagger 2.0)
• Annotations
• Documentation can be outdated
Swagger Problems
17

18. Spring Rest Docs
IMG http://spring.io 18

19. Spring Rest Docs
• Documentation is built from tests
• Clean code
• Documentation is part of a regular dev cycle
• Immediate reaction to API changes
• HATEOAS
19

20. Refactor
GREEN
RED
https://martinfowler.com/bliki/TestDrivenDevelopment.html
Classical Test Driven Development
20

21. Document
GREEN
Refactor
GREEN
RED
Spring Rest Docs Test Driven Documentation
21

22. Supports Integrated with
22
Spring Rest Docs

23. How does it work?
23

24. ResultActions actions = mockMvc.perform(get("/speakers/{id}", SPEAKER_ID))
.andDo(print());
actions.andExpect(status().isOk())
.andExpect(jsonPath("$.name", is("Roman Tsypuk")))
.andExpect(jsonPath("$.company", is("Lohika")));
MockMvc Test
ResultMatcher
24

25. ResultActions actions = mockMvc.perform(get("/speakers/{id}", SPEAKER_ID))
.andDo(print());
actions.andExpect(status().isOk())
.andExpect(jsonPath("$.name", is("Roman Tsypuk")))
.andExpect(jsonPath("$.company", is("Lohika")))
ResultHandler
MockMvc Key Players
.andDo( … )
25

26. Inside of ResultActions
ResultActions
MvcResultMockHttpServletRequest
encoding
content
contentType
contentLength
parameters
ServletResponse
headers
status
forwardUrl
includeUrl
errorMessage
HttpServletResponse
authType
cookie
header
method
pathInfo
HttpServletRequestServletRequest
attributes
charEncoding
content
contentType
parameters
serverPort
serverName
schema
async
MockHttpServletResponse
26

27. actions.andDo(document("{class-name}/{method-name}",
responseFields(
fieldWithPath("name").description("The name of the Speaker"),
fieldWithPath("company").description(”Speaker’s company"),
fieldWithPath("status").description("Hope only good :)"),
subsectionWithPath("_links").description("HATEOAS links")),
links(halLinks(),
linkWithRel("self").description("Link to Speaker"),
linkWithRel("topics").description("Topics of the Speaker"))));
ResultsHandler Registration
27

28. 28
DocumentTests TemplateSnippets
Spring Rest Docs Flow

29. Live Coding
29https://github.com/tsypuk/springrestdoc

30. • Admonitions (tips, warnings, cautions, importants)
• Text formatting
• Lists (ordered, checklists)
• Code blocks highlighting
• Images/files
• Extensions
Asciidoc is Awesome
30

31. • NEO4J https://neo4j.com/docs/java-reference/3.1/#call-procedure
• O’Reilly books
• CouchDB http://guide.couchdb.org/draft/consistency.html
• Enterprise Web Development http://enterprisewebbook.com/
• Bintray https://bintray.com/docs/api/
• JBoss CDI Java EE http://docs.jboss.org/cdi/spec/1.1/cdi-spec.html
• SpringFox https://springfox.github.io/springfox/docs/current/
Asciidoc is Widely Used
31

32. Migration from
Swagger
Челове с рюкзаком
Карта с маршрутом
IMG http://www.visolve.com/migration.php 32

33. Step 1: use swagger2markup (plug-in/dependency)
33
swagger2markup
paths
overview
definitions
security
Converted
From
Swagger
http://

34. Step 2: no TDDoc at this stage
34
DocumentTests TemplateSnippets
Converted
From
Swagger

35. Step 3: start using Spring Rest Docs
35
DocumentTests TemplateSnippets
Converted
From
Swagger
Spring
Rest Docs

36. Step 4: continue adding more sections
36
DocumentTests TemplateSnippets
Converted
From
Swagger
Spring
Rest Docs
Spring
Rest Docs

37. Step 5: all sections are under TDDoc control
37
DocumentTests TemplateSnippets
Spring
Rest Docs
Spring
Rest Docs
Spring
Rest Docs

38. Summary
38

39. Sources https://github.com/tsypuk/springrestdoc
39

40. Q&A
40
@tsypuk_r
tsypuk.conf@gmail.com
IMG http://www.melaclaro.com/

41. Links useful resources
• https://martinfowler.com/articles/richardsonMaturityModel.html
• https://www.tothepoint.company/blog/spring-rest-doc/
• https://opencredo.com/rest-api-tooling-review/
• https://speakerdeck.com/ankinson/documenting-restful-apis-webinar
• https://speakerdeck.com/ankinson/documenting-restful-apis-webinar
• https://projects.spring.io/spring-restdocs/
• https://causecode.com/blog/60/documenting-rest-api-grails-318-with-spring-rest-docs
• http://ditaa.sourceforge.net
• http://asciidoctor.org/docs/what-is-asciidoc/
41