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

Transcript

1. A Test-Driven Approach to Documenting RESTful APIs with Spring REST

   Docs Jenn Strater @codeJENNerator

2. @codeJENNerator Follow Along https://github.com/jlstrater/groovy-spring-boot-restdocs-example https://github.com/jlstrater/grails-spring-restdocs-example https://github.com/ratpack/example-books

3. @codeJENNerator About Me

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

5. @codeJENNerator About Me • Senior Consultant at Object Partners, Inc.

   • Co-Founder of Gr8Ladies

6. @codeJENNerator About Me • Senior Consultant at Object Partners, Inc.

   • Co-Founder of Gr8Ladies • 2016 - 2017 Fulbright US Student Program Selectee to Denmark

7. @codeJENNerator Background

8. @codeJENNerator Background • Creating RESTful APIs with Groovy

9. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

   Boot

10. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

    Boot • Grails

11. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

    Boot • Grails • Ratpack

12. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

    Boot • Grails • Ratpack • Documentation

13. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

    Boot • Grails • Ratpack • Documentation • Swagger

14. @codeJENNerator Background • Creating RESTful APIs with Groovy • Spring

    Boot • Grails • Ratpack • Documentation • Swagger • Asciidoctor

15. @codeJENNerator img src: https://flic.kr/p/rehEf5

16. @codeJENNerator I hate writing documentation! img src: https://flic.kr/p/rehEf5

17. @codeJENNerator Factors in Choosing a Documentation Solution

18. @codeJENNerator REST Maturity Model img src: http://martinfowler.com/articles/richardsonMaturityModel.html

19. @codeJENNerator REST Maturity Model img src: http://martinfowler.com/articles/richardsonMaturityModel.html

20. @codeJENNerator Endpoint Vs Resource Design

21. @codeJENNerator Endpoint Vs Resource Design VS

22. @codeJENNerator Central Information Security Http Verbs Error Handling Http Status

23. @codeJENNerator Multiple Services

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

25. @codeJENNerator Swagger

26. @codeJENNerator Swagger Approaches

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

28. @codeJENNerator Super Easy Install • io.springfox:springfox-swagger2 • io.springfox:springfox-swagger-ui

29. @codeJENNerator 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":
 .
 .
 .
 }

30. @codeJENNerator Considerations

31. @codeJENNerator Swagger UI • Springfox generated UI • Copy static

    files and customize

32. @codeJENNerator 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 }

33. @codeJENNerator 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 }

34. @codeJENNerator 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 }

35. @codeJENNerator 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

36. @codeJENNerator 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 }

37. @codeJENNerator Object Mapping img src: https://github.com/springfox/springfox/issues/281

38. @codeJENNerator Advantages

39. @codeJENNerator Swagger UI “Try-It” Button

40. @codeJENNerator The Alternative

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

42. @codeJENNerator Mixing Spring REST Docs and Swagger

43. @codeJENNerator Swagger2Markup https://swagger2markup.readme.io/

44. None
45. None

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

47. @codeJENNerator Test-Driven Documentation Green Red Refactor

48. @codeJENNerator Test-Driven Documentation

49. @codeJENNerator Test-Driven Documentation Red

50. @codeJENNerator Test-Driven Documentation Red

51. @codeJENNerator Test-Driven Documentation Document Red

52. @codeJENNerator Test-Driven Documentation Document Red

53. @codeJENNerator Test-Driven Documentation Document Green Red

54. @codeJENNerator Test-Driven Documentation Document Green Red

55. @codeJENNerator Test-Driven Documentation Document Green Red Refactor

56. @codeJENNerator Test-Driven Documentation Document Green Red Refactor

57. @codeJENNerator Advantages https://flic.kr/p/81RP5v

58. @codeJENNerator Advantages • Ensure documentation matches implementation https://flic.kr/p/81RP5v

59. @codeJENNerator Advantages • Ensure documentation matches implementation • Encourages writing

    more tests https://flic.kr/p/81RP5v

60. @codeJENNerator Advantages • Ensure documentation matches implementation • Encourages writing

    more tests • Reduces duplication https://flic.kr/p/81RP5v

61. @codeJENNerator Advantages • Ensure documentation matches implementation • Encourages writing

    more tests • Reduces duplication • Removes annotations from source https://flic.kr/p/81RP5v

62. @codeJENNerator Spring REST Docs

63. @codeJENNerator Overview projects.spring.io/spring-restdocs

64. @codeJENNerator Overview • Sponsored by Pivotal projects.spring.io/spring-restdocs

65. @codeJENNerator Overview • Sponsored by Pivotal • Project Lead •

    Andy Wilkinson projects.spring.io/spring-restdocs

66. @codeJENNerator Overview • Sponsored by Pivotal • Project Lead •

    Andy Wilkinson • Current Version • 1.1.1 projects.spring.io/spring-restdocs

67. @codeJENNerator Overview • Sponsored by Pivotal • Project Lead •

    Andy Wilkinson • Current Version • 1.1.1 projects.spring.io/spring-restdocs

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

69. @codeJENNerator 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

70. @codeJENNerator Groovier Spring REST docs • Spring Boot • Grails

    • Ratpack

71. @codeJENNerator Groovier Spring REST docs Example I

72. @codeJENNerator Groovier Spring REST docs Example I • Groovy Spring

    Boot Project • Level I/II Rest API

73. @codeJENNerator Groovier Spring REST docs Example I • Groovy Spring

    Boot Project • Level I/II Rest API + Asciidoctor Gradle plugin

74. @codeJENNerator Groovier Spring REST docs Example I • Groovy Spring

    Boot Project • Level I/II Rest API + Asciidoctor Gradle plugin + MockMVC and documentation to Spock tests

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

76. @codeJENNerator Groovy Spring Boot App • Start with lazybones spring

    boot app • Add mock endpoints for example https://github.com/jlstrater/groovy-spring-boot- restdocs-example

77. @codeJENNerator 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
 }
 }

78. @codeJENNerator Asciidoctor Gradle Plugin

79. @codeJENNerator 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'
 }


80. @codeJENNerator 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.

81. @codeJENNerator Converted to HTML

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

83. @codeJENNerator 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!”)) }

84. @codeJENNerator Web Context Setup void setup() {
 this.mockMvc = MockMvcBuilders

    .webAppContextSetup(this.context) .build()
 }

85. @codeJENNerator Web Context Setup void setup() {
 this.mockMvc = MockMvcBuilders

    .webAppContextSetup(this.context) .build()
 } If context is null, remember to add spock-spring!!

86. @codeJENNerator Spring REST docs

87. @codeJENNerator Gradle ext {
 snippetsDir = file('src/docs/generated-snippets')
 } testCompile “org.springframework.restdocs:spring-

    restdocs-mockmvc:1.0.1.RELEASE”


88. @codeJENNerator 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
 }

89. @codeJENNerator

90. @codeJENNerator 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()
 }

91. @codeJENNerator 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()
 }

92. @codeJENNerator 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))

93. @codeJENNerator 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'))
 ))
 }
 }

94. @codeJENNerator 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'))
 ))
 }
 }
95. None

96. @codeJENNerator POST

97. @codeJENNerator 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))

98. @codeJENNerator 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'))
 ))
 }
99. None

100. @codeJENNerator 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'))
 ))
 }

101. @codeJENNerator 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'))
 ))
 }

102. @codeJENNerator Failing Tests

103. @codeJENNerator Failing Tests

104. @codeJENNerator Generated Snippets {example-name} • curl-request.adoc • http-request.adoc • httpie-request.adoc

     • http-response.adoc • response-fields.adoc • request-parameters.adoc • request-parts.adoc src/docs/ generated-snippets

105. @codeJENNerator Generated Snippets {example-name} • curl-request.adoc • http-request.adoc • httpie-request.adoc

     • http-response.adoc • response-fields.adoc • request-parameters.adoc • request-parts.adoc src/docs/ generated-snippets

106. @codeJENNerator 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[]

107. @codeJENNerator Build Docs src/docs index.adoc src/main/ resources/public/ html5 index.html

108. @codeJENNerator http://jlstrater.github.io/groovy-spring-boot-restdocs-example

109. @codeJENNerator Support for Rest Assured img src: https://www.flickr.com/photos/dskley/15558668690 RECENTLY RELEASED

110. @codeJENNerator Groovier Spring REST docs • Grails • Ratpack

111. @codeJENNerator Groovier Spring REST docs Example II

112. @codeJENNerator Groovier Spring REST docs Example II • Grails 3.0.15

     with Web API Profile • Level II Rest API

113. @codeJENNerator Groovier Spring REST docs Example II • Grails 3.0.15

     with Web API Profile • Level II Rest API + Asciidoctor Gradle plugin

114. @codeJENNerator 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.RELEASE - RestAssured

115. @codeJENNerator 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.RELEASE - RestAssured + Publish to Github Pages

116. @codeJENNerator Simple Grails App

117. @codeJENNerator 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

118. @codeJENNerator 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' ]
 + }
 }

119. @codeJENNerator 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']
 + }
 }

120. @codeJENNerator Asciidoctor Gradle Plugin

121. @codeJENNerator Spring REST docs & https://github.com/jayway/rest-assured

122. @codeJENNerator Grails Specific Setup + testCompile “org.springframework.restdocs:spring-restdocs- restassured:1.1.0.RELEASE” asciidoctor {

     … + mustRunAfter integrationTest … }

123. @codeJENNerator @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()
 } }

124. @codeJENNerator @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()
 } }

125. @codeJENNerator @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()
 } }

126. @codeJENNerator 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))
 }

127. @codeJENNerator 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))
 }

128. @codeJENNerator 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))
 }

129. @codeJENNerator 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))
 }

130. @codeJENNerator 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'))
 }
 }

131. @codeJENNerator https://jlstrater.github.io/grails-spring-restdocs-example

132. @codeJENNerator 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

133. @codeJENNerator restdocs.gradle dependencies {
 testCompile ‘org.springframework.restdocs:spring-restdocs-restassured:1.1.1.RELEASE'
 }
 
 ext {


     snippetsDir = file('src/docs/generated-snippets')
 }
 
 task cleanTempDirs(type: Delete) {
 delete fileTree(dir: 'src/docs/generated-snippets')
 delete fileTree(dir: 'src/ratpack/public/docs')
 }
 
 test {
 dependsOn cleanTempDirs
 outputs.dir snippetsDir
 }
 
 asciidoctor {
 mustRunAfter test
 inputs.dir snippetsDir
 sourceDir = file('src/docs')
 separateOutputDirs = false
 outputDir "$projectDir/src/ratpack/public/docs"
 attributes 'snippets': snippetsDir,
 'source-highlighter': 'prettify',
 'imagesdir': 'images',
 'toc': 'left',
 'icons': 'font',
 'setanchors': 'true',
 'idprefix': '',
 'idseparator': '-',
 'docinfo1': 'true'
 }
 
 build.dependsOn asciidoctor


134. @codeJENNerator build.gradle plugins {
 id "io.ratpack.ratpack-groovy" version "1.2.0"
 . .

     .
 + id 'org.asciidoctor.convert' version '1.5.3'
 }
 
 repositories {
 jcenter() . . . + maven { url 'https://repo.spring.io/libs-snapshot' }
 } 
 //some CI config
 apply from: "gradle/ci.gradle"
 + apply from: "gradle/restdocs.gradle"


135. @codeJENNerator path(":isbn") {
 def isbn = pathTokens["isbn"]
 
 byMethod {


     get {
 bookService.find(isbn).
 single().
 subscribe { Book book ->
 if (book == null) {
 clientError 404
 } else {
 render book
 }
 }
 } ... }
 }
 
 byMethod {
 get {
 bookService.all().
 toList().
 subscribe { List<Book> books ->
 render json(books)
 }
 }
 post {
 parse(jsonNode()).
 observe().
 flatMap { input ->
 bookService.insert(
 input.get("isbn").asText(),
 input.get("quantity").asLong(),
 input.get("price").asDouble()
 )
 }.
 single().
 flatMap {
 bookService.find(it)
 }.
 single().
 subscribe { Book createdBook ->
 render createdBook
 }
 } }

136. @codeJENNerator path(":isbn") {
 def isbn = pathTokens["isbn"]
 
 byMethod {


     get {
 bookService.find(isbn).
 single().
 subscribe { Book book ->
 if (book == null) {
 clientError 404
 } else {
 render book
 }
 }
 } ... }
 }
 
 byMethod {
 get {
 bookService.all().
 toList().
 subscribe { List<Book> books ->
 render json(books)
 }
 }
 post {
 parse(jsonNode()).
 observe().
 flatMap { input ->
 bookService.insert(
 input.get("isbn").asText(),
 input.get("quantity").asLong(),
 input.get("price").asDouble()
 )
 }.
 single().
 flatMap {
 bookService.find(it)
 }.
 single().
 subscribe { Book createdBook ->
 render createdBook
 }
 } } Get a book by ISBN /api/books/1932394842

137. @codeJENNerator path(":isbn") {
 def isbn = pathTokens["isbn"]
 
 byMethod {


     get {
 bookService.find(isbn).
 single().
 subscribe { Book book ->
 if (book == null) {
 clientError 404
 } else {
 render book
 }
 }
 } ... }
 }
 
 byMethod {
 get {
 bookService.all().
 toList().
 subscribe { List<Book> books ->
 render json(books)
 }
 }
 post {
 parse(jsonNode()).
 observe().
 flatMap { input ->
 bookService.insert(
 input.get("isbn").asText(),
 input.get("quantity").asLong(),
 input.get("price").asDouble()
 )
 }.
 single().
 flatMap {
 bookService.find(it)
 }.
 single().
 subscribe { Book createdBook ->
 render createdBook
 }
 } } Get a book by ISBN /api/books/1932394842 Get all books /api/books

138. @codeJENNerator path(":isbn") {
 def isbn = pathTokens["isbn"]
 
 byMethod {


     get {
 bookService.find(isbn).
 single().
 subscribe { Book book ->
 if (book == null) {
 clientError 404
 } else {
 render book
 }
 }
 } ... }
 }
 
 byMethod {
 get {
 bookService.all().
 toList().
 subscribe { List<Book> books ->
 render json(books)
 }
 }
 post {
 parse(jsonNode()).
 observe().
 flatMap { input ->
 bookService.insert(
 input.get("isbn").asText(),
 input.get("quantity").asLong(),
 input.get("price").asDouble()
 )
 }.
 single().
 flatMap {
 bookService.find(it)
 }.
 single().
 subscribe { Book createdBook ->
 render createdBook
 }
 } } Get a book by ISBN /api/books/1932394842 Get all books /api/books Post to create a new book /api/books

139. @codeJENNerator import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.documentationConfiguration
 
 import com.jayway.restassured.builder.RequestSpecBuilder
 import com.jayway.restassured.specification.RequestSpecification
 import

     org.junit.Rule
 import org.springframework.restdocs.JUnitRestDocumentation
 import ratpack.examples.book.fixture.ExampleBooksApplicationUnderTest
 import ratpack.test.ApplicationUnderTest
 import spock.lang.Shared
 import spock.lang.Specification
 
 abstract class BaseDocumentationSpec extends Specification {
 
 @Shared
 ApplicationUnderTest aut = new ExampleBooksApplicationUnderTest()
 
 @Rule
 JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation('src/docs/generated-snippets')
 
 protected RequestSpecification documentationSpec
 
 void setup() {
 this.documentationSpec = new RequestSpecBuilder()
 .addFilter(documentationConfiguration(restDocumentation))
 .build()
 }
 }


140. @codeJENNerator class BookDocumentationSpec extends BaseDocumentationSpec {
 
 @Shared
 EmbeddedApp isbndb

     = GroovyEmbeddedApp.of {
 handlers {
 all {
 render '{"data" : [{"title" : "Learning Ratpack", "publisher_name" : "O\'Reilly Media", "author_data" : [{"id" : "dan_woods", "name" : "Dan Woods"}]}]}'
 }
 }
 }
 
 @Delegate
 TestHttpClient client = aut.httpClient
 RemoteControl remote = new RemoteControl(aut)
 
 
 def setupSpec() {
 System.setProperty('eb.isbndb.host', "http://${isbndb.address.host}:${isbndb.address.port}")
 System.setProperty('eb.isbndb.apikey', "fakeapikey")
 }
 
 def cleanupSpec() {
 System.clearProperty('eb.isbndb.host')
 }
 
 def setupTestBook() {
 requestSpec { RequestSpec requestSpec ->
 requestSpec.body.type("application/json")
 requestSpec.body.text(JsonOutput.toJson([isbn: "1932394842", quantity: 0, price: 22.34]))
 }
 post("api/book")
 }
 
 def cleanup() {
 remote.exec {
 get(Sql).execute("delete from books")
 }
 } . . .

141. @codeJENNerator void 'test and document list books'() {
 setup:
 setupTestBook()


     
 expect:
 given(this.documentationSpec)
 .contentType('application/json')
 .accept('application/json')
 .port(aut.address.port)
 .filter(document('books-list-example',
 preprocessRequest(modifyUris()
 .host('books.example.com')
 .removePort()),
 preprocessResponse(prettyPrint()),
 responseFields(
 fieldWithPath('[].isbn').description('The ISBN of the book'),
 fieldWithPath('[].quantity').description("The quantity of the book that is available"),
 fieldWithPath('[].price').description("The current price of the book"),
 fieldWithPath('[].title').description("The title of the book"),
 fieldWithPath('[].author').description('The author of the book'),
 fieldWithPath('[].publisher').description('The publisher of the book')
 )))
 .when()
 .get('/api/book')
 .then()
 .assertThat()
 .statusCode(is(200))
 }

142. @codeJENNerator Reusable Snippets protected final Snippet getBookFields() {
 responseFields(
 fieldWithPath('isbn').description('The

     ISBN of the book'),
 fieldWithPath('quantity').description("The quantity of the book that is available"),
 fieldWithPath('price').description("The current price of the book"),
 fieldWithPath('title').description("The title of the book"),
 fieldWithPath('author').description('The author of the book’), fieldWithPath('publisher').description('The publisher of the book’) )
 }

143. @codeJENNerator def "test and document create book"() {
 given:
 def

     setup = given(this.documentationSpec)
 .body('{"isbn": "1234567890", "quantity": 10, "price": 22.34}')
 .contentType('application/json')
 .accept('application/json')
 .port(aut.address.port)
 .filter(document('books-create-example',
 preprocessRequest(prettyPrint(),
 modifyUris()
 .host('books.example.com')
 .removePort()),
 preprocessResponse(prettyPrint()),
 bookFields,
 requestFields(
 fieldWithPath('isbn').type(JsonFieldType.STRING).description('book ISBN id'),
 fieldWithPath('quantity').type(JsonFieldType.NUMBER).description('quanity available'),
 fieldWithPath('price').type(JsonFieldType.NUMBER)
 .description('price of the item as a number without currency')
 ),))
 when:
 def result = setup
 .when()
 .post("api/book")
 then:
 result
 .then()
 .assertThat()
 .statusCode(is(200))
 }

144. @codeJENNerator def "test and document create book"() {
 given:
 def

     setup = given(this.documentationSpec)
 .body('{"isbn": "1234567890", "quantity": 10, "price": 22.34}')
 .contentType('application/json')
 .accept('application/json')
 .port(aut.address.port)
 .filter(document('books-create-example',
 preprocessRequest(prettyPrint(),
 modifyUris()
 .host('books.example.com')
 .removePort()),
 preprocessResponse(prettyPrint()),
 bookFields,
 requestFields(
 fieldWithPath('isbn').type(JsonFieldType.STRING).description('book ISBN id'),
 fieldWithPath('quantity').type(JsonFieldType.NUMBER).description('quanity available'),
 fieldWithPath('price').type(JsonFieldType.NUMBER)
 .description('price of the item as a number without currency')
 ),))
 when:
 def result = setup
 .when()
 .post("api/book")
 then:
 result
 .then()
 .assertThat()
 .statusCode(is(200))
 }

145. @codeJENNerator void 'test and document get individual book'() {
 setup:


     setupTestBook()
 
 expect:
 given(this.documentationSpec)
 .contentType('application/json')
 .accept('application/json')
 .port(aut.address.port)
 .filter(document('books-get-example',
 preprocessRequest(modifyUris()
 .host('books.example.com')
 .removePort()),
 preprocessResponse(prettyPrint()),
 bookFields))
 .when()
 .get("/api/book/1932394842")
 .then()
 .assertThat()
 .statusCode(is(200))
 }

146. @codeJENNerator 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/

147. @codeJENNerator Conclusion

148. @codeJENNerator

149. @codeJENNerator • API documentation is complex

150. @codeJENNerator • API documentation is complex • Choosing the right

     tool for the job not just about the easiest one to setup

151. @codeJENNerator • 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.

152. @codeJENNerator • 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.

153. @codeJENNerator 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