Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Test-Driven Documentation for your REST(ful) service

251 views

Published on

Building RESTful APIs in Java? Getting tired of the annotation bloat forced upon you by your API specification framework which haunts your RESTful service controllers and model objects? Finding yourself in the situation where your code isn’t always in synch with your specification or vice versa?
RAML and Swagger / OpenAPI are great specifications with powerful and shiny tooling, but they do also really have their downsides when it comes to messing with our code.

Fear not! There are other alternatives worth investigating. In this talk, we’ll take a look at how we recently build, designed and documented a public REST API by doing Test Driven Documentation with some help of AsciiDoc and Spring (Auto) REST Docs.

Published in: Software
  • Hello! Get Your Professional Job-Winning Resume Here - Check our website! https://vk.cc/818RFv
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Test-Driven Documentation for your REST(ful) service

  1. 1. Test-Driven Documentation for your RESTful service by Jeroen Reijn
  2. 2. JEROEN REIJN Software Architect at Luminis /Amsterdam • Focus on productivity and Developer Experience • Been building APIs for the Web since 2010 • Writes most of his code in Java • Tweets @jreijn
  3. 3. Let’s talk about Web APIs
  4. 4. source: https://www.programmableweb.com/
  5. 5. Streaming 1% RPC 10% REST 89% REST RPC Streaming GraphQL source: https://www.programmableweb.com/
  6. 6. REST
  7. 7. Source: http://geek-and-poke.com/geekandpoke/2013/6/14/insulting-made-easy
  8. 8. Richardson Maturity Model Source: https://www.martinfowler.com/articles/richardsonMaturityModel.html HATEOAS (Hypermedia as the Engine of Application State)
  9. 9. REST • Uniform interface • Resources • URIs • Representations • Hypermedia
  10. 10. Hypermedia • Links in resource representations • State navigations discoverable
  11. 11. Hypertext link specifications • HAL • JSON-LD • JSON API • Collection+JSON • Siren
  12. 12. Hypertext link specifications { "_links" : { "self" : { "href" : "http://localhost:8080/" }, "planets" : { "href" : "http://localhost:8080/planets" }, "people" : { "href" : "http://localhost:8080/people" } } }
  13. 13. Building an API Design BuildDocument
  14. 14. Let’s talk about API design
  15. 15. Specification driven vs Code driven
  16. 16. Specification Driven Design Contract Driven Design a.k.a
  17. 17. Manual spec
  18. 18. API design
  19. 19. RAML • RESTful API Modelling Language (RAML) • Based on YAML file format • Powerful designer api with auto completion • Code generation for Java • No native support for HATEOAS
  20. 20. API Blueprint / Apiary • Markdown flavoured syntax • Powerful designer UI • Documentation while designing • Java code generator support is *very* minimal
  21. 21. Postman • Postman client is great for testing APIs • Supports designing & documenting APIs • Has support for Api Mocks • Enables fast prototyping of APIs • Tools for different phases in the API lifecycle
  22. 22. Open API • Widely adopted community-driven specification for REST APIs • YAML and JSON based format • Programming language-agnostic interface • Allows both code first and contract first approaches to API design • Evolving specification (version 3.0 released in the summer of 2017)
  23. 23. Swagger • Tools around the OpenAPI specification • Swagger editor • Swagger-UI • Swagger Codegen (server and client libs and many languages) • Swagger Inspector
  24. 24. Swagger Codegen /** * Unique identifier representing a specific planet. * @return id **/ @ApiModelProperty(value = "Unique identifier representing a specific planet.") public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public Planet name(String name) { this.name = name; return this; }
  25. 25. Retrospect • API Design tools and platform are getting really powerful • OpenAPI seems to be the most widely adopted api spec • Generating code from your API specification is up to you
  26. 26. Code Driven Design
  27. 27. “ An API is only as good 
 as its documentation! ”
  28. 28. Let’s talk about API documentation
  29. 29. Manual documentation
  30. 30. Documentation based on specs HTML / PDF
  31. 31. Docs based on code @GetMapping(value = "/films/{id}") ResponseEntity<Film> getFilmById(@PathVariable(“id") String id);
  32. 32. Docs based on code @ApiOperation(value = "", nickname = “getfilmbyid", notes = "Get a specific film by id.", response = Film.class, authorizations = { @Authorization(value = "apikeyQuery") }, tags = {}) @ApiResponses(value = { @ApiResponse(code = 200, message = "A film.", response = Film.class)}) @GetMapping(value = “/films/{id}") ResponseEntity<Film> getFilmById(@ApiParam(value = "Id of the film.", required = true) @PathVariable("id") String id);
  33. 33. Swagger drawbacks • Hypermedia support not ‘final’ • Documentation is done through several annotations which are added in your implementation classes • API Implementation code overtime, gets overwhelmed with annotations • Documentation is URI centric • Documentation and API could become out-of-sync overtime
  34. 34. “ API documentation needs to be more then just endpoints and resources ”
  35. 35. Spring REST Docs “Document RESTful services by combining 
 hand-written documentation with 
 auto-generated snippets 
 produced with Spring MVC Test.”
  36. 36. Spring REST Docs • Documentation is built from tests • Supports hypermedia (HATEOAS) APIs • Immediate reaction to API changes • Keeps your code clean • Produces AsciiDoc snippets
  37. 37. Basic Spring MVC Test @Test public void testGetAllPlanets() throws Exception { mockMvc.perform(get("/planets").accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk()) .andExpect(jsonPath("$.length()",is(2))); }
  38. 38. With Spring REST Doc @Test public void testGetAllPlanets() throws Exception { mockMvc.perform(get("/planets").accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk()) .andExpect(jsonPath("$.length()",is(2))) .andDo(document("planets/get")); }
  39. 39. AsciiDoc snippets |=== |Path|Type|Description |`id` |`Number` |The id of the planet |`name` |`String` |The name of the planet |`diameter` |`Number` |The diameter of the planet |===
  40. 40. AsciiDoc Plain-text writing format. AsciiDoc documents can be translated into various formats, including HTML, DocBook, PDF and ePub. = Hello, DevCon! Jeroen Reijn <jeroen.reijn@luminis.eu> An introduction to documenting Hypermedia APIs with https://projects.spring.io/spring-restdocs/[Spring REST Docs]. == First Section * item 1 * item 2
  41. 41. Generating documentation Test Generated snippets AsciiDoctor pluginHand-written docs Code Document
  42. 42. Let’s build an API!
  43. 43. Spring Auto REST Docs • Extension for Spring REST Docs • Response field documentation generated by means of introspection • Partial support for documenting Hypermedia ‘links’ out of the box • DRY - Uses JavaDoc for generating documentation
  44. 44. Spring REST Docs advantages • Ability to focus on domain model rather than URI’s • ‘Guarantees’ that API documentation and implementation code are in-sync • Forces you to update documentation for any implementation changes • Ability to document with different payloads and explain different test scenarios • Ability to document remote APIs (with WebTestClient)
  45. 45. In retrospect • Documenting Hypermedia API is getting easier • Validating APIs against their documentation is still ‘hard’ • Spring REST Docs can help documenting and validating the API • Good documentation is key to working with an API
  46. 46. Those who stand for nothing, fall for anything - Alexander Hamilton ?Thank you Questions? is powered by Don’t forget to vote!

×