Test-Driven Documentation for your REST(ful) service

Slide 1

Slide 1 text

Test-Driven Documentation for your RESTful service by Jeroen Reijn

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Let’s talk about Web APIs

Slide 4

Slide 4 text

source: https://www.programmableweb.com/

Slide 5

Slide 5 text

Streaming 1% RPC 10% REST 89% REST RPC Streaming GraphQL source: https://www.programmableweb.com/

Slide 6

Slide 6 text

REST

Slide 7

Slide 7 text

Source: http://geek-and-poke.com/geekandpoke/2013/6/14/insulting-made-easy

Slide 8

Slide 8 text

Richardson Maturity Model Source: https://www.martinfowler.com/articles/richardsonMaturityModel.html HATEOAS (Hypermedia as the Engine of Application State)

Slide 9

Slide 9 text

REST • Uniform interface • Resources • URIs • Representations • Hypermedia

Slide 10

Slide 10 text

Hypermedia • Links in resource representations • State navigations discoverable

Slide 11

Slide 11 text

Hypertext link specifications • HAL • JSON-LD • JSON API • Collection+JSON • Siren

Slide 12

Slide 12 text

Hypertext link specifications { "_links" : { "self" : { "href" : "http://localhost:8080/" }, "planets" : { "href" : "http://localhost:8080/planets" }, "people" : { "href" : "http://localhost:8080/people" } } }

Slide 13

Slide 13 text

Building an API Design Build Document

Slide 14

Slide 14 text

Let’s talk about API design

Slide 15

Slide 15 text

Specification driven vs Code driven

Slide 16

Slide 16 text

Specification Driven Design Contract Driven Design a.k.a

Slide 17

Slide 17 text

Manual spec

Slide 18

Slide 18 text

API design

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

API Blueprint / Apiary • Markdown flavoured syntax • Powerful designer UI • Documentation while designing • Java code generator support is *very* minimal

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

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)

Slide 26

Slide 26 text

Swagger • Tools around the OpenAPI specification • Swagger editor • Swagger-UI • Swagger Codegen (server and client libs and many languages) • Swagger Inspector

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

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; }

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

Code Driven Design

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

“ An API is only as good   as its documentation! ”

Slide 34

Slide 34 text

Let’s talk about API documentation

Slide 35

Slide 35 text

No content

Slide 36

Slide 36 text

Manual documentation

Slide 37

Slide 37 text

Documentation based on specs HTML / PDF

Slide 38

Slide 38 text

Docs based on code @GetMapping(value = "/films/{id}") ResponseEntity getFilmById(@PathVariable(“id") String id);

Slide 39

Slide 39 text

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 getFilmById(@ApiParam(value = "Id of the film.", required = true) @PathVariable("id") String id);

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

“ API documentation needs to be more then just endpoints and resources ”

Slide 43

Slide 43 text

Spring REST Docs “Document RESTful services by combining   hand-written documentation with   auto-generated snippets   produced with Spring MVC Test.”

Slide 44

Slide 44 text

Spring REST Docs • Documentation is built from tests • Supports hypermedia (HATEOAS) APIs • Immediate reaction to API changes • Keeps your code clean • Produces AsciiDoc snippets

Slide 45

Slide 45 text

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))); }

Slide 46

Slide 46 text

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")); }

Slide 47

Slide 47 text

Slide 48

Slide 48 text

AsciiDoc Plain-text writing format. AsciiDoc documents can be translated into various formats, including HTML, DocBook, PDF and ePub. = Hello, DevCon! Jeroen Reijn An introduction to documenting Hypermedia APIs with https://projects.spring.io/spring-restdocs/[Spring REST Docs]. == First Section * item 1 * item 2

Slide 49

Slide 49 text

Generating documentation Test Generated snippets AsciiDoctor plugin Hand-written docs Code Document

Slide 50

Slide 50 text

Let’s build an API!

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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)

Slide 53

Slide 53 text

In retrospect • Documenting Hypermedia APIs 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

Slide 54

Slide 54 text

Those who stand for nothing, fall for anything - Alexander Hamilton ? Thank you Questions? is powered by Don’t forget to vote! Sources available @ https://github.com/jreijn/devcon-rest-tdd-demo