Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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.

Andreas Evers

August 04, 2016
Tweet

More Decks by Andreas Evers

Other Decks in Technology

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