Test Driven Documentation with Spring Rest Docs JEEConf2017
2 likes1,094 views
The document discusses the transition from Swagger to Spring REST Docs for API documentation, emphasizing test-driven documentation practices. It covers the benefits of Spring REST Docs, including automatic documentation generation from tests, improved code quality, and enhanced API discoverability through HATEOAS. Additionally, it outlines the steps for migrating from Swagger, showcasing the clean integration with the Spring framework.
![@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](https://image.slidesharecdn.com/springrestdocsjeeconf-170528065117/85/Test-Driven-Documentation-with-Spring-Rest-Docs-JEEConf2017-9-320.jpg)
Test Driven Documentation with Spring Rest Docs JEEConf2017
- 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
- 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
- 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
- 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
- 28. 28 DocumentTests TemplateSnippets Spring Rest Docs Flow
- 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
- 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
Editor's Notes
- #12: Screen X controller X methods