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

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

jlstrater
March 18, 2016

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.

jlstrater

March 18, 2016
Tweet

More Decks by jlstrater

Other Decks in Technology

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/[email protected]/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


    [email protected](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

    [email protected](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 = '[email protected]: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