Writing Comprehensive and Guaranteed Up-to-date REST API Documentation - SpringOne Platform 2016

RESTful APIs are eating the world, yet all too often the documentation can cause indigestion for the APIs' developers and their users. Developers have to deal with annotation overload, repetition, and an unpleasant writing environment. Users are then left with documentation that's inaccurate and difficult to use. It doesn't have to be this way.

This talk will introduce Spring REST Docs and its test-driven approach to RESTful API documentation. We'll look at how it combines the power of Asciidoctor and your integration tests to produce documentation that's accurate and easy-to-read, while keeping your code DRY and free from annotation overload. We'll also look at some of the features that are new in Spring REST Docs 1.1, including support for REST Assured and Markdown.

Transcript

1. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Writing Comprehensive and Guaranteed
   Up-to-date REST API Documentation
   By Andreas Evers
   @andreasevers
   

   View Slide

2. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Keep the documentation accurate
   2
   

   View Slide

3. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Document in the right place
   3
   Controller
   Jackson
   Response Entity
   HTTP response
   POJO
   

   View Slide

4. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Keep it DRY
   4
   @ResponseStatus(CREATED)
   HttpHeaders create(
   @RequestBody UserInput userInput) {
   …
   }
   @ExceptionHandler(
   IllegalArgumentException.class)
   ResponseEntity illegalArgument() {
   return new ResponseEntity<>(BAD_REQUEST);
   }
   @ApiResponses({
   @ApiResponse(code=400, message="…"),
   @ApiResponse(code=201, message="…")})
   return new ResponseEntity<>(BAD_REQUEST);
   

   View Slide

5. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Write docs in markdown or asciidoc
   5
   

   View Slide

6. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   6
   generated
   snippets
   manually written
   template
   generated
   HTML
   integration

   tests
   Icons created by Richard Slater, Ryan Choi, Guillaume Bahri, iconsmind.com from Noun Project
   

   View Slide

7. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Integration test
   7
   this.mockMvc.perform(get("/cars/{carId}","1"))
   .andExpect(status().isOk())
   .andDo(document("cars",
   pathParameters(
   parameterWithName("carId")
   .description("Id of the car")),
   responseFields(
   fieldWithPath("brand")
   .description("Brand of the car"))
   .and(this.otherFields)));
   

   View Slide

8. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Request snippets
   8
   [source,bash]
   ----
   $ curl 'http://localhost:8080/cars/1' -i
   ----
   [source,bash]
   ----
   $ http GET 'http://localhost:8080/cars/1'
   ----
   Curl Request
   HTTPie Request (new in 1.1)
   

   View Slide

9. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
   Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
   Request snippets
   9
   [source,http,options="nowrap"]
   ----
   GET /cars/1 HTTP/1.1
   Host: localhost
   ----
   HTTP Request
   

   View Slide

10. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Request path parameters snippet
    10
    ./cars/{carId}
    |===
    |Parameter|Description
    |carId
    |Id of the car
    |===
    

    View Slide

11. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Response snippet
    11
    [source,http,options=“nowrap"]
    ----
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Content-Length: 150
    {
    "brand" : "BMW",
    "constructionYear" : 2010
    }
    ----
    

    View Slide

12. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    All snippets
    12
    Request
    - Curl request
    - HTTP request
    - HTTPie request
    Request fields
    Request path parameters
    Request parameters
    Request headers
    Request parts (new in 1.1)
    Response
    Response fields
    Hypermedia links
    Response headers
    Response fields
    

    View Slide

13. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Documentation template
    13
    [[resources-car-get]]
    === Retrieving a car
    For retrieving a car, the following path parameter
    has to be used to indicate which car to retrieve:
    include::{snippets}/car-get/path-parameters.adoc[]
    For example, a curl request for the first car in the
    repository looks like this:
    include::{snippets}/car-get/curl-request.adoc[]
    

    View Slide

14. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Documentation HTML
    14
    

    View Slide

15. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Demo
    15
    

    View Slide

16. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to package the documentation

    in your project’s jar file
    16
    

    View Slide

17. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to customize the request or response

    before it is documented
    17
    

    View Slide

18. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Support for reusing common documentation
    18
    

    View Slide

19. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to add extra information to the snippets
    19
    

    View Slide

20. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to document constraints of fields
    20
    

    View Slide

21. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to ignore parts of the request or response

    during documentation
    21
    

    View Slide

22. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Possibility to switch off failing

    on inaccurate documentation
    22
    

    View Slide

23. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Easy to mark parts of the request or response

    as optional
    23
    

    View Slide

24. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Support for both JSON and XML
    24
    

    View Slide

25. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Support for REST Assured
    25
    

    View Slide

26. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Ideal for brownfield stubbing
    26
    

    View Slide

27. Unless otherwise indicated, these slides are © 2013-2016 Pivotal Software, Inc. and licensed under a
    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Thank you for your attention
    @andreasevers
    http://projects.spring.io/spring-restdocs/
    https://github.com/spring-projects/spring-restdocs
    @springcentral
    spring.io/blog
    @pivotal
    pivotal.io/blog
    @pivotalcf
    http://engineering.pivotal.io
    

    View Slide