Test Driven Docs Warsaw JUG 2018

Documenting RESTful APIs with Spring REST Docs By Jenn Strater
@codeJENNerator

@codeJENNerator Notes For Those Viewing These Slides Online • Bulleted
text like this indicates the key points mentioned on a previous slide. They may not have been included in the official presentation. • If this view does not support links, the links will work in the pdf. In speakerdeck, you can click the ‘download pdf’ button at the right.

@codeJENNerator Outline • API Documentation Background • Approaches to Documentation
• Considerations  • Test-Driven Documentation • Spring REST Docs • Examples

@codeJENNerator Follow Along https://speakerdeck.com/jlstrater/test-driven-docs-warsaw-jug-2018 https://github.com/jlstrater/groovy-spring-boot-restdocs-example https://github.com/ratpack/example-books https://github.com/jlstrater/spring-restdocs-public-api-example

@codeJENNerator About Me

@codeJENNerator

@codeJENNerator About Me • Co-founder of Gr8Ladies and talk about
women in the Groovy Community all over the world • Passionate about bring new people into the Groovy community through free introductory workshops called Gr8Workshops. • Senior Engineer at Zenjob as of June 2017. We’re hiring! zenjob.de/ careers • Spent the 2016-2017 academic year in Copenhagen working on OSS and taking classes through a Fulbright Grant. • Prior to the Fulbright Grant, I was a senior consultant at Object Partners, Inc. in Minneapolis, MN, USA. My work with Spring REST Docs started on a project at my client through them.

@codeJENNerator Audience Background • Creating RESTful APIs • Spring Boot
• Grails • Ratpack • API Documentation • Wiki Pages, Word Documents, Conﬂuence, etc • Asciidoc / Asciidoctor • Swagger / RAML

@codeJENNerator src: https://ﬂic.kr/p/rehEf5

@codeJENNerator src: https://ﬂic.kr/p/rehEf5 I hate writing documentation!*

@codeJENNerator Case Study

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

@codeJENNerator REST Maturity Model • I’m not really a fan
of the right vs wrong REST debate, but I like this categorization of APIs. • Most of our APIS were level one or two, but we wanted to have the ﬂexibility to use hypermedia • Spring REST docs includes support for level 3 / hypermedia • Swagger 2.0 did not support hypermedia. Swagger 3.0 (released end of July 2017) now does

Documenting RESTfullike APIs with Spring REST Docs By Jenn Strater
@codeJENNerator

@codeJENNerator REST Maturity Model Attribution: @Alvaro_Sanchez

@codeJENNerator Monolith vs Microservices • As architecture evolves, many companies
move from a central monolith to micro services or maybe even gateways and multi-tiered architectures. • For documentation, it was important to have: • a consistent look and feel • a way to show how the services can work together

@codeJENNerator Central Information Security Http Verbs Error Handling Http Status

@codeJENNerator Central Information • Central Information • For example, security
tokens, patterns for error messages, http verbs/status codes, etc • This information needs to be written out and deﬁned once; not on every endpoint.

@codeJENNerator Document Design

@codeJENNerator URI Centric

@codeJENNerator Central Information • Who’s seen this before? Of the
people who have never used swagger before, how many understand what this means? Even our CTO who is technical, didn’t want to spend time ﬁguring it out. Also, product teams. • This is a swagger ui example but the concept is not limited to Swagger. I have seen many different APIs document in this way. It’s not just URI centric, but also very developer centric. No matter whether you leave here choosing Swagger or Spring REST Docs, think about your users! • This is an example from Spring Rest Docs using Asciidoc. • Notice the very different way of organizing information on the second slide. Resource centric document design organizes information by topic and includes urls in the examples only. The information from generated solutions isn’t enough. We need the handwritten information too!

@codeJENNerator Available Tools

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML Documentation AsciiDoc Markdown Wikis

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML Documentation AsciiDoc Markdown Wikis Swagger
UI Swagger2Markup

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML Testing MockMVC RestAssured Documentation AsciiDoc
Markdown Wikis Swagger UI Swagger2Markup

Markdown Wikis Swagger UI Swagger2Markup AssertJ- Swagger Contract-First

Markdown Wikis Swagger UI Swagger2Markup Spring REST Docs AssertJ- Swagger Contract-First

The specification formerly known as

@codeJENNerator Swagger • Swagger is: — a lot of things
• At the core, it is a way to standardize and deﬁne HTTP APIs over RPC. • It is very popular because of the many plugins built on top of it for things such as generating client libraries, generating docs, and much more. • In earlier versions, it did not support hypermedia. Documenting across micro services was possible, but required a bit of setup. Depending on the library, some central information is duplicated.

Body Slide - Dark Background All body text is Proxima
Nova Regular • Subhead (18pt) • Level Two (18pt) • Level Three (18pt) • Level Four (18pt) Use the “Decrease/Increase Indent”   tools to change bullet levels Automation img src: https://flic.kr/p/eduUfU

Body Slide - Dark Background All body text is Proxima
Nova Regular • Subhead (18pt) • Level Two (18pt) • Level Three (18pt) • Level Four (18pt) Use the “Decrease/Increase Indent”   tools to change bullet levels img src: https://www.flickr.com/photos/ 24874528@N04/17125924230 SpringFox

@codeJENNerator SpringFox • SpringFox: • Generates a Swagger Speciﬁcation from
source • Is very easy to setup (in simple cases) • No OpenAPI Spec 3.0 support!

@codeJENNerator Custom Swagger Speciﬁcation { "swagger": "2.0", "info": { "version":
"1", "title": "My Service", "contact": { "name": "Company Name" }, "license": {} }, "host": "example.com", "basepath": "/docs" }

@codeJENNerator Swagger UI

@codeJENNerator URI Centric

@codeJENNerator SpringFox UI approaches • Use SpringFox library • Copy
static ﬁles and customize

@codeJENNerator Considerations

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

@codeJENNerator Customization • For any non-standard conﬁguration, you may have
to override the UI. • As one example, we were adding custom headers for oauth jwt tokens. At the time, it was not supported with springfox-ui.

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

@codeJENNerator img src: https://github.com/springfox/springfox/issues/281 https://github.com/swagger-api/swagger-core/issues/97

@codeJENNerator Customization • In Swagger/OpenAPI Spec 2.0, there was no
hypermedia support. • In OpenAPI Spec 3.0, there is some support for links

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

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 } Annotation Hell

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

@codeJENNerator Annotation Hell 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 }

@codeJENNerator Swagger Advantages

@codeJENNerator

@codeJENNerator “Try it” Button Alternatives

Curl -> curl 'http://localhost:8080/greetings' -i -H 'Content-Type: text/plain' HTTP/1.1 200
X-Application-Context: application:8080 Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Date: Thu, 26 Jan 2017 13:28:19 GMT [{"id":1,"message":"Hello"},{"id":2,"message":"Hi"},{"id":3,"message":"Hola"},{"id": 4,"message":"Olá"},{"id":5,"message":"Hej"}]

@codeJENNerator

@codeJENNerator https://www.npmjs.com/package/ restdocs-to-postman

@codeJENNerator Mix and Match

Swagger2Markup https://github.com/Swagger2Markup/swagger2markup

img src: http://www.elvenspirit.com/elf/wp-content/uploads/2011/10/IMG_3013.jpg FAIL!

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

@codeJENNerator Spring Cloud Contract https://cloud.spring.io/spring-cloud-contract/

@codeJENNerator Stubs

@codeJENNerator What problem are you trying to solve?

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML Documentation AsciiDoc Markdown Wikis

Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML Documentation AsciiDoc Markdown Wikis Swagger
UI Swagger2Markup

Markdown Wikis Swagger UI Swagger2Markup

Markdown Wikis Swagger UI Swagger2Markup AssertJ- Swagger Contract-First

Markdown Wikis Swagger UI Swagger2Markup Spring REST Docs AssertJ- Swagger Contract-First

Spring REST Docs

@codeJENNerator Green Red Refactor Test-Driven Development

@codeJENNerator Test-Driven Documentation

@codeJENNerator Red Test-Driven Documentation

@codeJENNerator Document Red Test-Driven Documentation

@codeJENNerator Document Green Red Test-Driven Documentation

@codeJENNerator Document Green Red Refactor Test-Driven Documentation

Winning Solution Test-Driven Documentation https://ﬂic.kr/p/5XiKxU Winning Solution

@codeJENNerator Winning Solution • Ensures documentation matches implementation • Encourages
writing more tests • Reduces duplication in docs and tests • Removes annotations from source

@codeJENNerator Spring REST Docs https://ﬂic.kr/p/5XiKxU

Game Changers https://ﬂic.kr/p/9Tiv3U

@codeJENNerator Game Changers •Generated code snippets •Tests fail when documentation
is missing or out-of- date •Rest APIs with Hypermedia •Ratpack •Dynamic routing doesn’t work with Swagger

@codeJENNerator About Spring REST Docs projects.spring.io/spring-restdocs @springrestdocs https://github.com/spring-projects/spring-restdocs

@codeJENNerator About Spring REST Docs •Start with reading the docs;
The written docs are good! •Overview •Sponsored by Pivotal •Project Lead - Andy Wilkinson •Current Version - 2.0.1 released April 4 •Twitter Account and Ofﬁcial Logo

@codeJENNerator About Spring REST Docs • Test-Driven Documentation with Spring
REST Docs (Java and Spring Boot) - Spring I/O 2016 Andy Wilkinson • Writing comprehensive and guaranteed up-to-date REST API documentation - SpringOne Platform 2016 Anders Evers

@codeJENNerator Out of the Box

@codeJENNerator Out of the Box • Testing Frameworks • MockMVC
• RestAssured • WebTestClient - NEW! • Build Tools • Gradle • Maven

@codeJENNerator Out of the Box

@codeJENNerator Out of the Box Documentation Format • AsciiDoc •
Markdown Sample Projects • Spring Boot • Grails • Slate • TestNG • And more!

@codeJENNerator Examples

@codeJENNerator Groovier Spring REST Docs • Spring Boot • Ratpack
• Grails

@codeJENNerator Groovier Spring REST Docs Example - Spring Boot •
Groovy Spring Boot Project • + Asciidoctor Gradle plugin • + Spring REST Docs WebTestClient to Spock tests • + Add to static assets during build and publish to GitHub pages

@codeJENNerator Groovier Spring REST Docs

@codeJENNerator Groovier Spring REST Docs Example - Spring Boot •
Start with lazybones spring boot app • Add mock endpoints for example https://github.com/jlstrater/groovy-spring-boot- restdocs-example • Updated to Spring Boot 2.0.0.M7 https://www.callicoder.com/reactive-rest-apis-spring- webﬂux-reactive-mongo/

@codeJENNerator

@codeJENNerator @RestController @RequestMapping('/greetings') class GreetingsController { @Autowired GreetingRepository greetingsRepository @PostMapping()
Mono<Greeting> createGreeting(@Valid @RequestBody Greeting greeting) { return greetingsRepository.save(greeting) } @GetMapping() Flux<Greeting> listAllGreetings() { return greetingsRepository.findAll() } @GetMapping('/{id}') Mono<Greeting> getGreetingById(@PathVariable(value = 'id') String greetingId) { greetingsRepository.findById(greetingId) } }

Mono<Greeting> createGreeting(@Valid @RequestBody Greeting greeting) { return greetingsRepository.save(greeting) } @GetMapping() Flux<Greeting> listAllGreetings() { return greetingsRepository.findAll() } @GetMapping('/{id}') Mono<Greeting> getGreetingById(@PathVariable(value = 'id') String greetingId) { greetingsRepository.findById(greetingId) } } Create a new Greeting

Mono<Greeting> createGreeting(@Valid @RequestBody Greeting greeting) { return greetingsRepository.save(greeting) } @GetMapping() Flux<Greeting> listAllGreetings() { return greetingsRepository.findAll() } @GetMapping('/{id}') Mono<Greeting> getGreetingById(@PathVariable(value = 'id') String greetingId) { greetingsRepository.findById(greetingId) } } Create a new Greeting List all greetings

Mono<Greeting> createGreeting(@Valid @RequestBody Greeting greeting) { return greetingsRepository.save(greeting) } @GetMapping() Flux<Greeting> listAllGreetings() { return greetingsRepository.findAll() } @GetMapping('/{id}') Mono<Greeting> getGreetingById(@PathVariable(value = 'id') String greetingId) { greetingsRepository.findById(greetingId) } } Create a new Greeting List all greetings Get a greeting by id

@codeJENNerator

@codeJENNerator AsciiDoc • [introduction] • = Introduction • The Example
API is a RESTful web service that shows how Spring REST docs works. • [[overview-http-verbs]] • == HTTP verbs • The Example API tries to adhere as closely as possible to standard HTTP and REST conventions in its • use of HTTP verbs. • |=== • | Verb | Usage • | `GET` • | Used to retrieve a resource

@codeJENNerator Asciidoctor Gradle Plugin

@codeJENNerator AsciiDoc Gradle Conﬁguration apply plugin: 'org.asciidoctor.convert' asciidoctor { backends
'html5' attributes 'source-highlighter' : 'prettify', 'imagesdir':'images', 'toc':'left', 'icons': 'font', 'setanchors':'true', 'idprefix':'', 'idseparator':'-', 'docinfo1':'true', }

@codeJENNerator

Project Reactor and the WebTestClient

@codeJENNerator Setup @CompileStatic @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) class BaseControllerSpec extends Specification
{ @Autowired ApplicationContext context protected WebTestClient webTestClient void setup() { this.webTestClient = WebTestClient.bindToApplicationContext(this.context) .configureClient() .baseUrl('/greetings') .build() } }

@codeJENNerator Setup @CompileStatic @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) class BaseControllerSpec extends Specification
{ @Autowired ApplicationContext context protected WebTestClient webTestClient void setup() { this.webTestClient = WebTestClient.bindToApplicationContext(this.context) .configureClient() .baseUrl('/greetings') .build() } } If context is null, remember to use spock-spring!!

@codeJENNerator WebTestClient Call and Assertions this.webTestClient.post().uri('/') .contentType(MediaType.APPLICATION_JSON) .accept(MediaType.APPLICATION_JSON) .body(BodyInserters.fromObject('{"message": “Hello
Warsaw JUG!"}')) .exchange() .expectStatus().isOk() .expectBody() .jsonPath('$.id').isNotEmpty() .jsonPath(‘$.message').isEqualTo('Hello Warsaw JUG!’)

@codeJENNerator

@codeJENNerator Spring REST Docs Gradle Conﬁguration dependencies { … testCompile
"org.springframework.restdocs:spring-restdocs-webtestclient:${springRestDocsVersion}" asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:${springRestDocsVersion}" } ext { snippetsDir = file('build/generated-snippets') } test { outputs.dir "$projectDir/src/main/resources/public" } asciidoctor { dependsOn test inputs.dir snippetsDir }

@codeJENNerator Spring REST Docs with WebTestClient (setup) @CompileStatic @SpringBootTest(webEnvironment =
SpringBootTest.WebEnvironment.RANDOM_PORT) class BaseControllerSpec extends Specification { @Rule JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation() @Autowired ApplicationContext context protected WebTestClient webTestClient void setup() { this.webTestClient = WebTestClient.bindToApplicationContext(this.context) .configureClient() .baseUrl('/greetings') .filter(documentationConfiguration(restDocumentation)) .build() }

@codeJENNerator Spring REST Docs with WebTestClient (tests) void 'test and
document creating a greeting with a custom name'() { expect: this.webTestClient.post().uri('/') .contentType(MediaType.APPLICATION_JSON) .accept(MediaType.APPLICATION_JSON) .body(BodyInserters.fromObject('{"message": "Hello Warsaw JUG!"}')) .exchange() .expectStatus().isOk() .expectBody() .jsonPath('$.id').isNotEmpty() .jsonPath('$.message').isEqualTo('Hello Warsaw JUG!') .consumeWith(document('greetings-post-example', preprocessRequest(prettyPrint()), requestFields( fieldWithPath('message').type(JsonFieldType.STRING) .description("The greeting's message"))))

@codeJENNerator Spring REST Docs with WebTestClient (tests) void 'test and
document get of a list of greetings'() { expect: this.webTestClient.get().uri('/').accept(MediaType.APPLICATION_JSON) .exchange() .expectStatus().isOk() .expectBody() .consumeWith(document('greetings-list-example', preprocessResponse(prettyPrint()), responseFields(greetingList))) } FieldDescriptor[] greetingList = new FieldDescriptor().with { [fieldWithPath('[].id').type(JsonFieldType.STRING).optional() .description("The greeting's id"), fieldWithPath('[].message').type(JsonFieldType.STRING) .description("The greeting's message")]

Error Messages

@codeJENNerator

Generated Snippets By Default When Specified curl-request.adoc response-fields.adoc http-request.adoc request-parameters.adoc
httpie-request.adoc request-parts.adoc http-response.adoc path-parameters.adoc request body request-parts.adoc response body

@codeJENNerator http-request.adoc [source,http,options="nowrap"] ---- POST /greetings/ HTTP/1.1 Content-Type: application/json Accept:
application/json Host: localhost:8080 Content-Length: 45 { "message" : "Hello Warsaw JUG!” } ----

response-ﬁelds.adoc

@codeJENNerator +

@codeJENNerator Adding The Snippets [[overview-errors]] == 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-ﬁelds.adoc[] For example, a request that attempts to delete on the greetings endpoint will produce a `405 Method Not Allowed` response: operation::error-example[snippets='curl-request,http-request,http-response'] [[resources]] = Resources include::resources/greetings.adoc[]

@codeJENNerator

@codeJENNerator Building the docs • . src/docs/ asciidoc index.adoc build/asciidoc/
html5 index.html .gradlew asciidoctor

@codeJENNerator Building the docs • .

@codeJENNerator Publishing Strategies

@codeJENNerator Publishing Strategies • Hook in asciidoctor with the gradle
build task • Run the asciidoctor test separately (but make sure to run AFTER the tests) • Send to static resources directory in the current app or send to a remote site (for example Github Pages

@codeJENNerator

@codeJENNerator http://api.example.com/docs

@codeJENNerator 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/groovy-spring-boot-restdocs-example.git' pages { from(file('build/asciidoc/html5')) } }

@codeJENNerator 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/groovy-spring-boot-restdocs-example.git' pages { from(file('build/asciidoc/html5')) } } If you use this method, remember to deploy docs at the same time as the project!

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

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

@codeJENNerator ➜ build git:(master) restdocs-to-postman --input generated-snippets --export-format postman --determine-folder
secondLastFolder --output postman-collection.json

@codeJENNerator Special Use Case

@codeJENNerator   +@WebMvcTest(controllers = GreetingsController)  +@AutoConfigureRestDocs(  + outputDir = "build/generated-snippets", 
+ uriHost = “api.example.com”,  + uriPort = 8080  ) class BaseControllerSpec extends Specification {   // @Rule  // JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation('src/ docs/generated-snippets')    + @Autowired  protected MockMvc mockMvc  //  // @Autowired  // private WebApplicationContext context  //  // void setup() {  // this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)  // .apply(documentationConfiguration(this.restDocumentation))  // .build()  // } }

@codeJENNerator Groovier Spring REST Docs • Spring Boot • Ratpack
• Grails

@codeJENNerator Support for Rest- Assured

@codeJENNerator

@codeJENNerator Groovier Spring REST Docs Example - Ratpack • Ratpack
Example Project • https://github.com/ratpack/example-books • Spring RESTdocs RestAssured • https://github.com/ratpack/example-books/pull/25

@codeJENNerator Groovier Spring REST Docs Example - Ratpack 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  }  } }

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

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

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

https://github.com/jayway/rest-assured

@codeJENNerator abstract class BaseDocumentationSpec extends Specification {    @Shared  ApplicationUnderTest
aut = new ExampleBooksApplicationUnderTest()    @Rule  JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation()    protected RequestSpecification documentationSpec    void setup() {  this.documentationSpec = new RequestSpecBuilder()  .addFilter(documentationConfiguration(restDocumentation))  .build()  }  }

@codeJENNerator

@codeJENNerator Documenting Public APIs

@codeJENNerator Blog Post https://jennstrater.blogspot.com/2017/01/using-spring- rest-docs-to-document.html

@codeJENNerator Outcomes

@codeJENNerator Outcomes • Made it to production! :) • Team
was happy with Spring REST Docs • Other dev teams like to see the examples

@codeJENNerator Read the Docs for More On… • Adding Security
and Headers • Documenting Constraints • Hypermedia Support • XML Support • Using Markdown instead of Asciidoc • Third Party Extensions for WireMock(Spring Cloud Contracts), Jersey, AutoRestDocs, RAML

@codeJENNerator Conclusion

@codeJENNerator 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. • I still hate writing boilerplate documentation, but at least it’s a little less painful now.

@codeJENNerator Next Steps • Join #spring-restdocs on gitter • Join
the Groovy Community on Slack - groovycommunity.com

Test Driven Docs Warsaw JUG 2018

Test Driven Docs Warsaw JUG 2018

More Decks by jlstrater

Other Decks in Technology

Featured

Transcript