Test-Driven Approaches to Documenting RESTful APIs

As presented at Twin Cities Code Camp on April 16, 2016
---------------------
Documentation generated from source code is very popular. Solutions such as Swagger are available for many different languages and frameworks. However, limitations of annotation based tools are becoming apparent. An overwhelming number of documentation annotations make for great docs but muddy the source code. Then, something changes and the docs are out of date again.

That is where test-driven approaches come in.

Test-driven documentation solutions, such as Spring Rest Docs, generate example snippets for requests and responses from tests ensuring both code coverage and accurate documentation. It can even fail the build when documentation becomes out of date. This session will walk through how to implement test-driven documentation solutions for groovy ecosystem technologies like Spring Boot and Grails. Attendees should have a basic understanding of AsciiDoc and how to construct RESTful APIs in Spring Boot and/or Grails.

---------------------
Jennifer “Jenn” Strater is a software engineer with a passion for developing and designing applications using new and innovative technologies. Her strengths are in the service layer including building RESTful APIs. Jenn also has experience with relational and NoSQL databases, devops, front-end, and mobile in the healthcare and transportation industries. She learns new tools and systems quickly and introduces new technology learned through local community groups, involvement in the international Groovy community, and when speaking at or attending regional, national, and international conferences.

Jenn is the co-founder of the organization Gr8Ladies and has organized Gr8Workshops for developers interested in an overview and crash course in Groovy technologies. She has presented at various Minnesota tech events, the Grace Hopper Celebration of Women in Computing, Greach, Gr8Conf EU, Gr8Conf US, and Devoxx Belgium.

Starting in September 2016, Jenn will be a master's student at the Technical University of Denmark studying static analysis and compilers with a focus on Groovy with funding from the Fulbright U.S. student program.

Transcript

1. Test-Driven Approaches
   to Documenting RESTful
   APIs
   Jenn Strater
   @codeJENNerator
   Twin Cities Code Camp
   April 16, 2016
   NEW!!!
   

   View Slide

2. Follow Along
   https://speakerdeck.com/jlstrater/test-driven-
   approaches-to-documenting-restful-apis-1
   https://github.com/jlstrater/groovy-spring-boot-restdocs-example
   https://github.com/jlstrater/grails-spring-restdocs-example
   https://github.com/ratpack/example-books
   

   View Slide

3. About Me
   

   View Slide

4. About Me
   • Senior Consultant at Object
   Partners, Inc.
   

   View Slide

5. About Me
   • Senior Consultant at Object
   Partners, Inc.
   • Co-Founder of Gr8Ladies
   

   View Slide

6. About Me
   • Senior Consultant at Object
   Partners, Inc.
   • Co-Founder of Gr8Ladies
   • 2016 - 2017 Fulbright US
   Student Program Selectee to
   Denmark
   

   View Slide

7. Background
   

   View Slide

8. Background
   • Creating RESTful APIs with Groovy
   • Spring Boot
   • Grails
   • Ratpack
   

   View Slide

9. Background
   • Creating RESTful APIs with Groovy
   • Spring Boot
   • Grails
   • Ratpack
   • Documentation
   • Swagger
   • Asciidoctor
   

   View Slide

10. img src: https://flic.kr/p/rehEf5
    

    View Slide

11. I hate writing documentation!
    img src: https://flic.kr/p/rehEf5
    

    View Slide

12. Factors in Choosing a
    Documentation Solution
    

    View Slide

13. REST Maturity Model
    img src: http://martinfowler.com/articles/richardsonMaturityModel.html
    

    View Slide

14. REST Maturity Model
    img src: http://martinfowler.com/articles/richardsonMaturityModel.html
    

    View Slide

15. Endpoint Vs Resource
    Design
    

    View Slide

16. Endpoint Vs Resource
    Design
    VS
    

    View Slide

17. Central Information
    Security
    Http
    Verbs
    Error
    Handling
    Http
    Status
    

    View Slide

18. Multiple Services
    

    View Slide

19. Headers
    img src: http://sergiodelamo.es/how-to-secure-your-grails-3-api-with-spring-security-rest-for-grails/
    

    View Slide

20. Versioning
    v1 v2 v3
    

    View Slide

21. Swagger
    

    View Slide

22. Swagger Approaches
    

    View Slide

23. SpringFox
    img src: https://www.flickr.com/photos/24874528@N04/17125924230
    

    View Slide

24. Super Easy Install
    • io.springfox:springfox-swagger2
    • io.springfox:springfox-swagger-ui
    

    View Slide

25. Custom JSON
    {

    "swagger": "2.0",

    "info": {

    "version": "1",

    "title": "My Service",

    "contact": {

    "name": "Company Name"

    },

    "license": {}

    },

    "host": "example.com",

    "basepath": "/docs",

    "tags": [

    {

    "name": "group name",

    "description": "what this group of api endpoints is for",

    }

    ],

    "paths": {

    "/api/v1/groupname/resource":

    .

    .

    .

    }
    

    View Slide

26. Considerations
    

    View Slide

27. Swagger UI
    • Springfox generated UI
    • Copy static files and customize
    

    View Slide

28. 1 @Secured(‘ROLE_ALLOWED_TO_PERFORM_ACTION’)

    2 @RequestMapping(value = '/v1/serviceName/actionName', method =
    3 RequestMethod.POST)

    4 @ApiOperation(value = '/actionName',

    5 notes = 'Enables or disables setting via "1" or "0", respectively')

    6 @ApiResponses(value = [

    7 @ApiResponse(code = 200, response = CustomSettingResponse, message =
    8 ‘Successful setting update'),

    9 @ApiResponse(code = 400, response = ErrorResponse, message = 'Invalid
    10 user input'),

    11 @ApiResponse(code = 500, response = ErrorResponse, message = 'Unexpected
    12 server error')

    13 ])

    14 CustomSettingResponse setSetting(@RequestBody CustomModel settingsValue) {

    15 SaveSettingUpdateRequest request = new SaveSettingUpdateRequest (

    16 settingsValue.fieldOne,

    17 [new TransformedSetting(SettingEnum.POSSIBLE_ENUM_VALUE,
    18 new Double(settingsValue.value))]

    19 )

    20 api.saveUpdatedSetting(request)

    21 }
    

    View Slide

29. Annotation Hell
    1 @Secured(‘ROLE_ALLOWED_TO_PERFORM_ACTION’)

    2 @RequestMapping(value = '/v1/serviceName/actionName', method =
    3 RequestMethod.POST)

    4 @ApiOperation(value = '/actionName',

    5 notes = 'Enables or disables setting via "1" or "0", respectively')

    6 @ApiResponses(value = [

    7 @ApiResponse(code = 200, response = CustomSettingResponse, message =
    8 ‘Successful setting update'),

    9 @ApiResponse(code = 400, response = ErrorResponse, message = 'Invalid
    10 user input'),

    11 @ApiResponse(code = 500, response = ErrorResponse, message = 'Unexpected
    12 server error')

    13 ])

    14 CustomSettingResponse setSetting(@RequestBody CustomModel settingsValue) {

    15 SaveSettingUpdateRequest request = new SaveSettingUpdateRequest (

    16 settingsValue.fieldOne,

    17 [new TransformedSetting(SettingEnum.POSSIBLE_ENUM_VALUE,
    18 new Double(settingsValue.value))]

    19 )

    20 api.saveUpdatedSetting(request)

    21 }
    

    View Slide

30. Annotation Hell
    1 @Secured(‘ROLE_ALLOWED_TO_PERFORM_ACTION’)

    2 @RequestMapping(value = '/v1/serviceName/actionName', method =
    3 RequestMethod.POST)

    4 @ApiOperation(value = '/actionName',

    5 notes = 'Enables or disables setting via "1" or "0", respectively')

    6 @ApiResponses(value = [

    7 @ApiResponse(code = 200, response = CustomSettingResponse, message =
    8 ‘Successful setting update'),

    9 @ApiResponse(code = 400, response = ErrorResponse, message = 'Invalid
    10 user input'),

    11 @ApiResponse(code = 500, response = ErrorResponse, message = 'Unexpected
    12 server error')

    13 ])

    14 CustomSettingResponse setSetting(@RequestBody CustomModel settingsValue) {

    15 SaveSettingUpdateRequest request = new SaveSettingUpdateRequest (

    16 settingsValue.fieldOne,

    17 [new TransformedSetting(SettingEnum.POSSIBLE_ENUM_VALUE,
    18 new Double(settingsValue.value))]

    19 )

    20 api.saveUpdatedSetting(request)

    21 }
    

    View Slide

31. Annotation Hell
    1 @Secured(‘ROLE_ALLOWED_TO_PERFORM_ACTION’)

    2 @RequestMapping(value = '/v1/serviceName/actionName', method =
    3 RequestMethod.POST)

    4 @ApiOperation(value = '/actionName',

    5 notes = 'Enables or disables setting via "1" or "0", respectively')

    6 @ApiResponses(value = [

    7 @ApiResponse(code = 200, response = CustomSettingResponse, message =
    8 ‘Successful setting update'),

    9 @ApiResponse(code = 400, response = ErrorResponse, message = 'Invalid
    10 user input'),

    11 @ApiResponse(code = 500, response = ErrorResponse, message = 'Unexpected
    12 server error')

    13 ])

    14 CustomSettingResponse setSetting(@RequestBody CustomModel settingsValue) {

    15 SaveSettingUpdateRequest request = new SaveSettingUpdateRequest (

    16 settingsValue.fieldOne,

    17 [new TransformedSetting(SettingEnum.POSSIBLE_ENUM_VALUE,
    18 new Double(settingsValue.value))]

    19 )

    20 api.saveUpdatedSetting(request)

    21 }
    X
    

    View Slide

32. 1 @Secured(‘ROLE_ALLOWED_TO_PERFORM_ACTION’)

    2 @RequestMapping(value = '/v1/serviceName/actionName', method =
    3 RequestMethod.POST)
    4 CustomSettingResponse setSetting(@RequestBody CustomModel settingsValue) {

    5 SaveSettingUpdateRequest request = new SaveSettingUpdateRequest (

    6 settingsValue.fieldOne,

    7 [new TransformedSetting(SettingEnum.POSSIBLE_ENUM_VALUE,
    8 new Double(settingsValue.value))]

    9 )

    10 api.saveUpdatedSetting(request)

    11 }
    

    View Slide

33. Object Mapping
    img src: https://github.com/springfox/springfox/issues/281
    

    View Slide

34. Advantages
    

    View Slide

35. Swagger UI
    “Try-It” Button
    

    View Slide

36. Postman Run Button
    src: https://www.getpostman.com/img/v1/docs/run_btn_ux/run_btn_ux_1.png
    

    View Slide

37. Notable Alternatives &
    Enhancements
    

    View Slide

38. Swagger2Markup
    https://swagger2markup.readme.io/
    

    View Slide

39. View Slide

40. View Slide

41. AssertJ-Swagger
    https://github.com/RobWin/assertj-swagger
    FAIL!
    img src: http://www.elvenspirit.com/elf/wp-content/uploads/2011/10/IMG_3013.jpg
    

    View Slide

42. Test-Driven Documentation
    Green
    Red Refactor
    

    View Slide

43. Test-Driven Documentation
    

    View Slide

44. Test-Driven Documentation
    Red
    

    View Slide

45. Test-Driven Documentation
    Red
    

    View Slide

46. Test-Driven Documentation
    Document
    Red
    

    View Slide

47. Test-Driven Documentation
    Document
    Red
    

    View Slide

48. Test-Driven Documentation
    Document Green
    Red
    

    View Slide

49. Test-Driven Documentation
    Document Green
    Red
    

    View Slide

50. Test-Driven Documentation
    Document Green
    Red Refactor
    

    View Slide

51. Test-Driven Documentation
    Document Green
    Red Refactor
    

    View Slide

52. Advantages
    https://flic.kr/p/81RP5v
    

    View Slide

53. Advantages
    • Ensure documentation matches
    implementation
    https://flic.kr/p/81RP5v
    

    View Slide

54. Advantages
    • Ensure documentation matches
    implementation
    • Encourages writing more tests
    https://flic.kr/p/81RP5v
    

    View Slide

55. Advantages
    • Ensure documentation matches
    implementation
    • Encourages writing more tests
    • Reduces duplication
    https://flic.kr/p/81RP5v
    

    View Slide

56. Advantages
    • Ensure documentation matches
    implementation
    • Encourages writing more tests
    • Reduces duplication
    • Removes annotations from
    source
    https://flic.kr/p/81RP5v
    

    View Slide

57. Spring REST Docs
    

    View Slide

58. Overview
    • Sponsor
    • Pivotal
    • Project Lead
    • Andy Wilkinson
    projects.spring.io/spring-restdocs
    

    View Slide

59. Game Changers
    • Generated code snippets
    • Tests fail when documentation
    is missing or out-of-date
    • Can’t Use Swagger
    • Level III Rest APIs —
    Hypermedia
    • Ratpack
    https://flic.kr/p/9Tiv3U
    

    View Slide

60. Getting Started
    • Documentation - Spring Projects
    • Documenting RESTful Apis - SpringOne2GX 2015 -
    Andy Wilkinson
    • Spring REST Docs - Documenting RESTful APIs
    using your tests - Devoxx Belgium 2015 -
    Anders Evers
    

    View Slide

61. Groovier Spring REST docs
    • Spring Boot
    • Grails
    • Ratpack
    

    View Slide

62. Groovier Spring REST docs
    Example I
    

    View Slide

63. Groovier Spring REST docs
    Example I
    • Groovy Spring Boot Project
    • Level I/II Rest API
    

    View Slide

64. Groovier Spring REST docs
    Example I
    • Groovy Spring Boot Project
    • Level I/II Rest API
    + Asciidoctor Gradle plugin
    

    View Slide

65. Groovier Spring REST docs
    Example I
    • Groovy Spring Boot Project
    • Level I/II Rest API
    + Asciidoctor Gradle plugin
    + MockMVC and documentation to Spock tests
    

    View Slide

66. Groovier Spring REST docs
    Example I
    • Groovy Spring Boot Project
    • Level I/II Rest API
    + Asciidoctor Gradle plugin
    + MockMVC and documentation to Spock tests
    + Add to static assets during build
    

    View Slide

67. Groovy Spring Boot App
    • Start with lazybones spring boot app
    • Add mock endpoints for example
    https://github.com/jlstrater/groovy-spring-boot-
    restdocs-example
    

    View Slide

68. Endpoints
    @CompileStatic

    @RestController

    @RequestMapping('/hello')

    @Slf4j

    class ExampleController {

    

    @RequestMapping(method = RequestMethod.GET, produces =
    'application/json', consumes = 'application/json')

    Example list() {

    new Example(name: 'World')

    }

    

    @RequestMapping(method = RequestMethod.POST, produces =
    'application/json', consumes = 'application/json')

    Example list(@RequestBody Example example) {

    example

    }

    }
    

    View Slide

69. Asciidoctor Gradle
    Plugin
    

    View Slide

70. Install
    classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'

    apply plugin: 'org.asciidoctor.convert'

    

    asciidoctor {

    sourceDir = file('src/docs')

    outputDir "$projectDir/src/main/resources/public"

    backends 'html5'

    attributes 'source-highlighter' : 'prettify',

    'imagesdir':'images',

    'toc':'left',

    'icons': 'font',

    'setanchors':'true',

    'idprefix':'',

    'idseparator':'-',

    'docinfo1':'true'

    }

    

    View Slide

71. Example AsciiDoc
    = Gr8Data API Guide

    Jenn Strater;

    :doctype: book

    :icons: font

    :source-highlighter: highlightjs

    :toc: left

    :toclevels: 4

    :sectlinks:

    

    [introduction]

    = Introduction

    

    The Gr8Data API is a RESTful web service for aggregating and displaying gender
    ratios from

    various companies across the world. This document outlines how to submit data from
    your company or team and

    how to access the aggregate data.

    

    [[overview-http-verbs]]

    == HTTP verbs

    

    The Gr8Data API tries to adhere as closely as possible to standard HTTP and REST
    conventions in its

    use of HTTP verbs.
    

    View Slide

72. Converted to HTML
    

    View Slide

73. MockMvc Test
    src: http://www.javacodegeeks.com/2013/04/spring-mvc-introduction-in-testing.html
    

    View Slide

74. Stand Alone Setup
    class ExampleControllerSpec extends Specification {

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(
    new ExampleController()).build()

    }

    

    void 'test and document get with example endpoint’() {

    when:

    ResultActions result = this.mockMvc.perform(
    get(‘/hello’).contentType(MediaType.APPLICATION_JSON))
    then:

    result
    .andExpect(status().isOk())
    .andExpect(jsonPath("name").value("World"))

    .andExpect(jsonPath("message").value("Hello, World!”))
    }
    

    View Slide

75. Web Context Setup
    void setup() {

    this.mockMvc = MockMvcBuilders
    .webAppContextSetup(this.context)
    .build()

    }
    

    View Slide

76. Web Context Setup
    void setup() {

    this.mockMvc = MockMvcBuilders
    .webAppContextSetup(this.context)
    .build()

    }
    If context is null,
    remember to add
    spock-spring!!
    

    View Slide

77. Spring REST docs
    

    View Slide

78. Gradle
    ext {

    snippetsDir = file(
    'src/docs/generated-snippets')

    }
    testCompile “org.springframework.restdocs:spring-
    restdocs-mockmvc:1.0.1.RELEASE”

    

    View Slide

79. Gradle
    asciidoctor {

    dependsOn test

    sourceDir = file('src/docs')

    outputDir "$projectDir/src/main/resources/public"

    + inputs.dir snippetsDir

    backends 'html5'

    attributes 'source-highlighter' : 'prettify',

    'imagesdir':'images',

    'toc':'left',

    'icons': 'font',

    'setanchors':'true',

    'idprefix':'',

    'idseparator':'-',

    'docinfo1':'true',

    + 'snippets': snippetsDir,

    }
    

    View Slide

80. Setup & GET
    

    View Slide

81. Setup & GET
    class ExampleControllerSpec extends Specification {

    

    @Rule

    RestDocumentation restDocumentation = new RestDocumentation('src/docs/generated-snippets')

    

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(new ExampleController())

    .apply(documentationConfiguration(this.restDocumentation))

    .build()

    }
    

    View Slide

82. Setup & GET
    class ExampleControllerSpec extends Specification {

    

    @Rule

    RestDocumentation restDocumentation = new RestDocumentation('src/docs/generated-snippets')

    

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(new ExampleController())

    .apply(documentationConfiguration(this.restDocumentation))

    .build()

    }
    

    View Slide

83. Setup & GET
    class ExampleControllerSpec extends Specification {

    

    @Rule

    RestDocumentation restDocumentation = new RestDocumentation('src/docs/generated-snippets')

    

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(new ExampleController())

    .apply(documentationConfiguration(this.restDocumentation))

    .build()

    }
    void 'test and document get with example endpoint'() {

    when:

    ResultActions result = this.mockMvc.perform(get('/hello')

    .contentType(MediaType.APPLICATION_JSON))
    

    View Slide

84. Setup & GET
    class ExampleControllerSpec extends Specification {

    

    @Rule

    RestDocumentation restDocumentation = new RestDocumentation('src/docs/generated-snippets')

    

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(new ExampleController())

    .apply(documentationConfiguration(this.restDocumentation))

    .build()

    }
    void 'test and document get with example endpoint'() {

    when:

    ResultActions result = this.mockMvc.perform(get('/hello')

    .contentType(MediaType.APPLICATION_JSON))
    then:

    result

    .andExpect(status().isOk())
    .andExpect(jsonPath('name').value('World'))

    .andExpect(jsonPath('message').value('Hello, World!'))

    .andDo(document('hello-get-example', preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath('name').type(JsonFieldType.STRING).description('name'),

    fieldWithPath('message').type(JsonFieldType.STRING).description('hello world'))

    ))

    }

    }
    

    View Slide

85. Setup & GET
    class ExampleControllerSpec extends Specification {

    

    @Rule

    RestDocumentation restDocumentation = new RestDocumentation('src/docs/generated-snippets')

    

    protected MockMvc mockMvc

    

    void setup() {

    this.mockMvc = MockMvcBuilders.standaloneSetup(new ExampleController())

    .apply(documentationConfiguration(this.restDocumentation))

    .build()

    }
    void 'test and document get with example endpoint'() {

    when:

    ResultActions result = this.mockMvc.perform(get('/hello')

    .contentType(MediaType.APPLICATION_JSON))
    then:

    result

    .andExpect(status().isOk())
    .andExpect(jsonPath('name').value('World'))

    .andExpect(jsonPath('message').value('Hello, World!'))

    .andDo(document('hello-get-example', preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath('name').type(JsonFieldType.STRING).description('name'),

    fieldWithPath('message').type(JsonFieldType.STRING).description('hello world'))

    ))

    }

    }
    

    View Slide

86. View Slide

87. POST
    

    View Slide

88. POST
    void 'test and document post with example endpoint and custom name'() {

    when:
    ResultActions result = this.mockMvc.perform(post(‘/hello')
    .content(new ObjectMapper()
    .writeValueAsString(new Example(name: 'mockmvc test’))
    .contentType(MediaType.APPLICATION_JSON))
    

    View Slide

89. POST
    void 'test and document post with example endpoint and custom name'() {

    when:
    ResultActions result = this.mockMvc.perform(post(‘/hello')
    .content(new ObjectMapper()
    .writeValueAsString(new Example(name: 'mockmvc test’))
    .contentType(MediaType.APPLICATION_JSON))
    then:

    result

    .andExpect(status().isOk())

    .andExpect(jsonPath('name').value('mockmvc test'))

    .andExpect(jsonPath('message').value('Hello, mockmvc test!'))
    .andDo(document('hello-post-example',
    preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath('name').type(JsonFieldType.STRING)

    .description('name'),

    fieldWithPath('message').type(JsonFieldType.STRING)

    .description('hello world'))

    ))

    }
    

    View Slide

90. View Slide

91. List Example
    void 'test and document get of a list from example endpoint'() {

    when:

    ResultActions result = this.mockMvc.perform(get('/hello/list')

    .contentType(MediaType.APPLICATION_JSON))

    

    then:

    result

    .andExpect(status().isOk())

    .andDo(document('hello-list-example',
    preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath('[].message').type(JsonFieldType.STRING)

    .description('message'))

    ))

    }
    

    View Slide

92. List Example
    void 'test and document get of a list from example endpoint'() {

    when:

    ResultActions result = this.mockMvc.perform(get('/hello/list')

    .contentType(MediaType.APPLICATION_JSON))

    

    then:

    result

    .andExpect(status().isOk())

    .andDo(document('hello-list-example',
    preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath('[].message').type(JsonFieldType.STRING)

    .description('message'))

    ))

    }
    

    View Slide

93. Central Info - Errors
    void 'test and document error format’() {
    when:

    ResultActions result = this.mockMvc.perform(put('/error')

    .contentType(MediaType.APPLICATION_JSON)

    .requestAttr(RequestDispatcher.ERROR_STATUS_CODE, 405)

    .requestAttr(RequestDispatcher.ERROR_REQUEST_URI, '/hello')

    .requestAttr(RequestDispatcher.ERROR_MESSAGE,
    "Request method 'PUT' not supported"))

    

    View Slide

94. Central Info - Errors
    void 'test and document error format’() {
    when:

    ResultActions result = this.mockMvc.perform(put('/error')

    .contentType(MediaType.APPLICATION_JSON)

    .requestAttr(RequestDispatcher.ERROR_STATUS_CODE, 405)

    .requestAttr(RequestDispatcher.ERROR_REQUEST_URI, '/hello')

    .requestAttr(RequestDispatcher.ERROR_MESSAGE,
    "Request method 'PUT' not supported"))

    then:

    result
    .andExpect(status().isMethodNotAllowed())

    .andDo(document('error-example', preprocessResponse(prettyPrint()),

    responseFields(

    fieldWithPath(‘error')
    .description('The HTTP error that occurred, e.g. `Bad Request`'),

    fieldWithPath(‘message')
    .description('A description of the cause of the error'),

    fieldWithPath('path').description('The path to which the request was made'),

    fieldWithPath('status').description('The HTTP status code, e.g. `400`'),

    fieldWithPath(‘timestamp')
    .description('The time, in milliseconds, at which the error occurred'))

    ))

    }
    

    View Slide

95. Failing Tests
    

    View Slide

96. Failing Tests
    

    View Slide

97. Generated Snippets
    {example-name}
    • curl-request.adoc
    • http-request.adoc
    • http-response.adoc
    • response-fields.adoc
    • request-parameters.adoc
    src/docs/
    generated-snippets
    

    View Slide

98. Add Snippets to AsciiDoc
    == Errors

    

    Whenever an error response (status code >= 400) is returned, the
    body will contain a JSON object

    that describes the problem. The error object has the following
    structure:

    

    include::{snippets}/error-example/response-fields.adoc[]

    

    For example, a request that attempts to apply a non-existent tag
    to a note will produce a

    `400 Bad Request` response:

    

    include::{snippets}/error-example/http-response.adoc[]

    

    [[resources]]

    = Resources

    

    include::resources/example.adoc[]
    

    View Slide

99. Build Docs
    src/docs
    index.adoc
    src/main/
    resources/public/
    html5
    index.html
    

    View Slide

100. http://jlstrater.github.io/groovy-spring-boot-restdocs-example
     

     View Slide

101. Support for Rest Assured
     img src: https://www.flickr.com/photos/dskley/15558668690
     

     View Slide

102. Groovier Spring REST docs
     • Grails
     • Ratpack
     

     View Slide

103. Groovier Spring REST docs
     Example II
     

     View Slide

104. Groovier Spring REST docs
     Example II
     • Grails 3.0.15 with Web API Profile
     • Level II Rest API
     

     View Slide

105. Groovier Spring REST docs
     Example II
     • Grails 3.0.15 with Web API Profile
     • Level II Rest API
     + Asciidoctor Gradle plugin
     

     View Slide

106. Groovier Spring REST docs
     Example II
     • Grails 3.0.15 with Web API Profile
     • Level II Rest API
     + Asciidoctor Gradle plugin
     + Spring REST docs 1.1.0.M1 - RestAssured
     

     View Slide

107. Groovier Spring REST docs
     Example II
     • Grails 3.0.15 with Web API Profile
     • Level II Rest API
     + Asciidoctor Gradle plugin
     + Spring REST docs 1.1.0.M1 - RestAssured
     + Publish to Github Pages
     

     View Slide

108. Simple Grails App
     

     View Slide

109. Simple Grails App
     ->grails create-app —profile=web-api —inplace
     grails> create-domain-resource com.example.Note
     | Created grails-app/domain/com/example/Note.groovy
     | Created src/test/groovy/com/example/NoteSpec.groovy
     grails> create-domain-resource com.example.Tag
     | Created grails-app/domain/com/example/Tag.groovy
     | Created src/test/groovy/com/example/TagSpec.groovy
     

     View Slide

110. package com.example

     

     import grails.rest.Resource

     

     +@Resource(uri='/notes', readOnly = false, formats = ['json', 'xml'])

     class Note {

     + Long id

     + String title

     + String body

     

     + static hasMany = [tags: Tag]

     + static mapping = {

     + tags joinTable: [name: "mm_notes_tags", key: 'mm_note_id' ]

     + }

     }
     

     View Slide

111. package com.example
     import grails.rest.Resource

     +@Resource(uri='/tags', readOnly = false, formats = ['json', 'xml'])

     class Tag {

     + Long id

     + String name

     

     + static hasMany = [notes: Note]

     + static belongsTo = Note

     + static mapping = {

     + notes joinTable: [name: "mm_notes_tags", key: 'mm_tag_id']

     + }

     }
     

     View Slide

112. Asciidoctor Gradle
     Plugin
     

     View Slide

113. Spring REST docs
     &
     https://github.com/jayway/rest-assured
     

     View Slide

114. Grails Specific Setup
     + testCompile “org.springframework.restdocs:spring-
     restdocs-restassured:1.1.0.M1”
     asciidoctor {
     …
     + mustRunAfter integrationTest
     …
     }
     

     View Slide

115. @Integration

     @Rollback

     class ApiDocumentationSpec extends Specification {

     @Rule

     JUnitRestDocumentation restDocumentation =
     new JUnitRestDocumentation('src/docs/generated-snippets')

     

     protected RequestSpecification documentationSpec

     

     void setup() {

     this.documentationSpec = new RequestSpecBuilder()

     .addFilter(documentationConfiguration(restDocumentation))

     .build()

     }
     }
     

     View Slide

116. @Integration

     @Rollback

     class ApiDocumentationSpec extends Specification {

     @Rule

     JUnitRestDocumentation restDocumentation =
     new JUnitRestDocumentation('src/docs/generated-snippets')

     

     protected RequestSpecification documentationSpec

     

     void setup() {

     this.documentationSpec = new RequestSpecBuilder()

     .addFilter(documentationConfiguration(restDocumentation))

     .build()

     }
     }
     

     View Slide

117. @Integration

     @Rollback

     class ApiDocumentationSpec extends Specification {

     @Rule

     JUnitRestDocumentation restDocumentation =
     new JUnitRestDocumentation('src/docs/generated-snippets')

     

     protected RequestSpecification documentationSpec

     

     void setup() {

     this.documentationSpec = new RequestSpecBuilder()

     .addFilter(documentationConfiguration(restDocumentation))

     .build()

     }
     }
     

     View Slide

118. void 'test and document notes list request'() {

     expect:

     given(this.documentationSpec)

     .accept(MediaType.APPLICATION_JSON.toString())

     .filter(document('notes-list-example',

     preprocessRequest(modifyUris()

     .host('api.example.com')

     .removePort()),

     preprocessResponse(prettyPrint()),

     responseFields(

     fieldWithPath('[].class').description('the class of the resource'),

     fieldWithPath('[].id').description('the id of the note'),

     fieldWithPath('[].title').description('the title of the note'),

     fieldWithPath('[].body').description('the body of the note'),

     fieldWithPath(‘[].tags').type(JsonFieldType.ARRAY)
     .description('the list of tags associated with the note'),

     )))

     .when()

     .port(8080)

     .get('/notes')

     .then()

     .assertThat()

     .statusCode(is(200))

     }
     

     View Slide

119. void 'test and document notes list request'() {

     expect:

     given(this.documentationSpec)

     .accept(MediaType.APPLICATION_JSON.toString())

     .filter(document('notes-list-example',

     preprocessRequest(modifyUris()

     .host('api.example.com')

     .removePort()),

     preprocessResponse(prettyPrint()),

     responseFields(

     fieldWithPath('[].class').description('the class of the resource'),

     fieldWithPath('[].id').description('the id of the note'),

     fieldWithPath('[].title').description('the title of the note'),

     fieldWithPath('[].body').description('the body of the note'),

     fieldWithPath(‘[].tags').type(JsonFieldType.ARRAY)
     .description('the list of tags associated with the note'),

     )))

     .when()

     .port(8080)

     .get('/notes')

     .then()

     .assertThat()

     .statusCode(is(200))

     }
     

     View Slide

120. void 'test and document create new note'() {

     expect:

     given(this.documentationSpec)

     .accept(MediaType.APPLICATION_JSON.toString())

     .contentType(MediaType.APPLICATION_JSON.toString())

     .filter(document('notes-create-example',

     preprocessRequest(modifyUris()

     .host('api.example.com')

     .removePort()),

     preprocessResponse(prettyPrint()),

     requestFields(

     fieldWithPath('title').description('the title of the note'),

     fieldWithPath('body').description('the body of the note'),

     fieldWithPath(‘tags').type(JsonFieldType.ARRAY)
     .description('a list of tags associated to the note')

     ),

     responseFields(

     fieldWithPath('class').description('the class of the resource'),

     fieldWithPath('id').description('the id of the note'),

     fieldWithPath('title').description('the title of the note'),

     fieldWithPath('body').description('the body of the note'),

     fieldWithPath(‘tags').type(JsonFieldType.ARRAY)
     .description('the list of tags associated with the note'),

     )))

     .body('{ "body": "My test example", "title": "Eureka!",
     "tags": [{"name": "testing123"}] }')

     .when()

     .port(8080)

     .post('/notes')

     .then()

     .assertThat()

     .statusCode(is(201))

     }
     

     View Slide

121. void 'test and document create new note'() {

     expect:

     given(this.documentationSpec)

     .accept(MediaType.APPLICATION_JSON.toString())

     .contentType(MediaType.APPLICATION_JSON.toString())

     .filter(document('notes-create-example',

     preprocessRequest(modifyUris()

     .host('api.example.com')

     .removePort()),

     preprocessResponse(prettyPrint()),

     requestFields(

     fieldWithPath('title').description('the title of the note'),

     fieldWithPath('body').description('the body of the note'),

     fieldWithPath(‘tags').type(JsonFieldType.ARRAY)
     .description('a list of tags associated to the note')

     ),

     responseFields(

     fieldWithPath('class').description('the class of the resource'),

     fieldWithPath('id').description('the id of the note'),

     fieldWithPath('title').description('the title of the note'),

     fieldWithPath('body').description('the body of the note'),

     fieldWithPath(‘tags').type(JsonFieldType.ARRAY)
     .description('the list of tags associated with the note'),

     )))

     .body('{ "body": "My test example", "title": "Eureka!",
     "tags": [{"name": "testing123"}] }')

     .when()

     .port(8080)

     .post('/notes')

     .then()

     .assertThat()

     .statusCode(is(201))

     }
     

     View Slide

122. Publish Docs
     publish.gradle
     buildscript {

     repositories {

     jcenter()

     }

     

     dependencies {

     classpath 'org.ajoberstar:gradle-git:1.1.0'

     }

     }

     

     apply plugin: 'org.ajoberstar.github-pages'

     

     githubPages {

     repoUri = 'git@github.com:jlstrater/grails-spring-boot-restdocs-example.git'

     pages {

     from(file('build/docs'))

     }

     }
     

     View Slide

123. https://jlstrater.github.io/grails-spring-restdocs-example
     

     View Slide

124. Groovier Spring REST docs
     Example III
     • Ratpack Example Project
     • https://github.com/ratpack/example-books
     • Spring RESTdocs RestAssured
     • https://github.com/ratpack/example-books/pull/25
     

     View Slide

125. Line By Line
     https://github.com/ratpack/example-books/pull/25
     

     View Slide

126. Read the docs for more on..
     • Adding Security and Headers
     • Documenting Constraints
     • Hypermedia Support
     • Using Markdown instead of Asciidoc
     http://projects.spring.io/spring-restdocs/
     

     View Slide

127. Conclusion
     

     View Slide

128. View Slide

129. • API documentation is complex
     

     View Slide

130. • API documentation is complex
     • Choosing the right tool for the job not just about the
     easiest one to setup
     

     View Slide

131. • API documentation is complex
     • Choosing the right tool for the job not just about the
     easiest one to setup
     • Spring REST Docs is a promising tool to enforce
     good testing and documentation practices without
     muddying source code.
     

     View Slide

132. • API documentation is complex
     • Choosing the right tool for the job not just about the
     easiest one to setup
     • Spring REST Docs is a promising tool to enforce
     good testing and documentation practices without
     muddying source code.
     • I still hate writing documentation, but at least it’s a
     little less painful now.
     

     View Slide

133. Questions?
     https://github.com/jlstrater/groovy-spring-boot-restdocs-example
     https://github.com/jlstrater/grails-spring-restdocs-example
     https://github.com/ratpack/example-books
     https://flic.kr/p/5DeuzB
     

     View Slide