A Test Driven Approach to Documenting RESTful APIs with Spring REST Docs

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.

Transcript

1. A Test-Driven Approach to
   Documenting RESTful APIs
   with Spring REST Docs
   Jenn Strater
   @jennstrater
   Object Partners Tech Talk
   March 18, 2016
   

   View Slide

2. About Me
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

6. Background
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

    View Slide

11. Factors in Choosing a
    Documentation Solution
    

    View Slide

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

    View Slide

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

    View Slide

14. Endpoint Vs Resource
    Design
    

    View Slide

15. Endpoint Vs Resource
    Design
    VS
    

    View Slide

16. Central Information
    Security
    Http
    Verbs
    Error
    Handling
    Http
    Status
    

    View Slide

17. Multiple Services
    

    View Slide

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

    View Slide

19. Versioning
    v1 v2 v3
    

    View Slide

20. Swagger
    

    View Slide

21. Swagger Approaches
    

    View Slide

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

    View Slide

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

    View Slide

24. 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

25. Considerations
    

    View Slide

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

    View Slide

27. 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

28. 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

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

    View Slide

31. 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

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

    View Slide

33. Advantages
    

    View Slide

34. Swagger UI
    “Try-It” Button
    

    View Slide

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

    View Slide

36. Notable Alternatives &
    Enhancements
    

    View Slide

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

    View Slide

38. View Slide

39. View Slide

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

    View Slide

41. Test-Driven Documentation
    Green
    Red Refactor
    

    View Slide

42. Test-Driven Documentation
    

    View Slide

43. Test-Driven Documentation
    Red
    

    View Slide

44. Test-Driven Documentation
    Red
    

    View Slide

45. Test-Driven Documentation
    Document
    Red
    

    View Slide

46. Test-Driven Documentation
    Document
    Red
    

    View Slide

47. Test-Driven Documentation
    Document Green
    Red
    

    View Slide

48. Test-Driven Documentation
    Document Green
    Red
    

    View Slide

49. Test-Driven Documentation
    Document Green
    Red Refactor
    

    View Slide

50. Test-Driven Documentation
    Document Green
    Red Refactor
    

    View Slide

51. Advantages
    • Ensure documentation matches implementation
    • Encourages writing more tests
    • Reduces duplication in docs and tests
    • Removes annotations from source
    

    View Slide

52. Spring REST Docs
    

    View Slide

53. Game Changers
    • Generated code snippets
    • Tests fail when documentation is missing or out-of-
    date
    • Supports Level III Rest APIs (Hypermedia)
    

    View Slide

54. 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

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

    View Slide

56. Groovier Spring REST docs
    Example I
    

    View Slide

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

    View Slide

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

    View Slide

59. 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

60. 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

61. 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

62. 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

63. Asciidoctor Gradle
    Plugin
    

    View Slide

64. 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

65. 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

66. Converted to HTML
    

    View Slide

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

    View Slide

68. 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

69. Web Context Setup
    void setup() {

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

    }
    

    View Slide

70. Web Context Setup
    void setup() {

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

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

    View Slide

71. Spring REST docs
    

    View Slide

72. Gradle
    ext {

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

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

    

    View Slide

73. 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

74. Setup & GET
    

    View Slide

75. 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

76. 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

77. 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

78. 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

79. 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

80. View Slide

81. POST
    

    View Slide

82. 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

83. 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

84. View Slide

85. 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

86. 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

87. 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

88. 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

89. Failing Tests
    

    View Slide

90. Failing Tests
    

    View Slide

91. 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

92. 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

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

    View Slide

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

    View Slide

95. Rest Assured - 1.1.0
    Grails & Ratpack
    img src: https://www.flickr.com/photos/dskley/15558668690
    

    View Slide

96. Groovier Spring REST docs
    Example II
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

     View Slide

101. Simple Grails App
     

     View Slide

102. 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

103. 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

104. 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

105. Asciidoctor Gradle
     Plugin
     

     View Slide

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

     View Slide

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

     View Slide

108. @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

109. @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

110. 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

111. 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

112. 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

113. 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

114. 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

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

     View Slide

116. 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

117. Conclusion
     • 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

118. 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