test driven docs javaland 2019

@codeJENNerator March 20, 2019 Javaland Jenn Strater Documenting RESTful APIs
with Spring REST Docs

@codeJENNerator • Bulleted text like this indicates the key points
mentioned on a previous slide. They may not have been included in the ofﬁcial 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 • Documenting RESTful APIs with Spring REST Docs (this
talk): • English • Groovy • Gradle • REST-like APIs • focus: how to build documentation • Schnittstellen-Dokumentation mit Spring REST Docs with Gerrit Meier: • German • Java • Maven • Hypermedia • focus: live coding examples

@codeJENNerator https://speakerdeck.com/jlstrater/test-driven-docs-javaland-2019 https://github.com/jlstrater/groovy-spring-boot-restdocs-example Follow Along

@codeJENNerator • Open Source • Build Automation • Commercial SaaS
Product (on-premises) • Development Productivity • for Gradle AND Apache Maven Gradle Products

@codeJENNerator Before Gradle

@codeJENNerator • Several years experience as a software engineer mostly
with APIs • Spring REST Docs user and contributor since 2015 • Organizer of various Groovy community groups and events • GR8DI, GR8Conf, Groovy community slack Before Gradle

@codeJENNerator Audience Background

@codeJENNerator • Creating RESTful APIs • Spring Boot • JavaEE/Jakarta/
Microproﬁle • Ratpack Audience Background

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

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

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

✦ Approaches to Documentation ✦ Considerations ✦ Building Documentation ✦
Spring REST Docs

Case Study

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

@codeJENNerator • 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 REST Maturity Model

@codeJENNerator Attribution: @Alvaro_Sanchez

@codeJENNerator • 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 Monolith vs Microservices

@codeJENNerator Central Information Security Http Verbs Error Handling Http Status

@codeJENNerator • 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. Keep it DRY. Central Information

@codeJENNerator Document Design

@codeJENNerator

@codeJENNerator • 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! Document Design

@codeJENNerator

@codeJENNerator • 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 other information too! Document Design

@codeJENNerator Available Tools

@codeJENNerator

@codeJENNerator Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML

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

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

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

AsciiDoc Markdown Wikis Swagger UI Swagger2Markup AssertJ- Swagger Contract-First

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

@codeJENNerator Deﬁnitions Swagger (OpenAPI Speciﬁcation) RAML

@codeJENNerator

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

@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 Automation img src: https://flic.kr/p/eduUfU

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

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

@codeJENNerator Swagger UI

@codeJENNerator

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

Spring REST Docs

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

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

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

@codeJENNerator https://github.com/swagger-api/swagger-core/issues/97

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

@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

@codeJENNerator

@codeJENNerator 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"}]

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

@codeJENNerator Spring REST Docs

@codeJENNerator • What problem are you trying to solve? •
What kind of documentation do you need to solve that problem? Summary

Spring REST Docs

@codeJENNerator AsciiDoc = Example API Guide Jenn Strater; :doctype: book
:icons: font :source-highlighter: highlightjs :toc: left :toclevels: 4 :sectlinks: [introduction] = Introduction The Example API is a RESTful web service that shows how Spring REST docs works. Interact with these endpoints in https://documenter.getpostman.com/view/6964523/ S17nVWHG#627c80fe-7520-1ff0-8f73-9b989042bd3e[image:postman-logo.png[Postman, title="Postman", width=100]]. [[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.

@codeJENNerator Asciidoctor Gradle Plugin https://asciidoctor.org/docs/asciidoctor-gradle-plugin/

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

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

@codeJENNerator

@codeJENNerator • Docs-as-Code, arc42, AsciiDoc, Gradle & Co. im Einsatz
by Ralf Müller (yesterday & April 8 at Dortmund JUG). • Test-Driven Approaches to Documentation by Jenn Strater April 2 at MicroXchg in Berlin. • Asciidoctor: Because Writing Docs Does Not Have to Suck by Andres Almiray April 4 at K15t TeamTalks in Stuttgart. More on Asciidoc

Spring REST Docs

@codeJENNerator Green Red Refactor Test-Driven Development

@codeJENNerator Document Green Red Refactor Test-Driven Documentation

@codeJENNerator Winning Solution https://ﬂic.kr/p/5XiKxU Winning Solution

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

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

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

@codeJENNerator • 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 History of Spring REST Docs

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

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

@codeJENNerator •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 Game Changers

@codeJENNerator Out of the Box

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

@codeJENNerator Out of the Box

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

Example

@codeJENNerator • 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 Spring REST Docs Example

@codeJENNerator Groovy Spring REST Docs

@codeJENNerator

@codeJENNerator Project Reactor and the WebTestClient

@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 @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() } } Setup

@Autowired ApplicationContext context protected WebTestClient webTestClient void setup() { this.webTestClient = WebTestClient.bindToApplicationContext(this.context) .configureClient() .baseUrl('/greetings') .build() } } Setup If context is null, remember to use spock-spring!!

@codeJENNerator WebTestClient Call and Assertions void 'test and document creating
a greeting with a custom name'() { when: def result = this.webTestClient.post().uri('/') .contentType(MediaType.APPLICATION_JSON) .accept(MediaType.APPLICATION_JSON) .body(BodyInserters.fromObject('{"message": "Hello!"}')) .exchange() .expectStatus().isOk() .expectBody() .jsonPath('$.id').isNotEmpty() .jsonPath('$.message').isEqualTo('Hello!') JsonSlurper slurper = new JsonSlurper() greetingId = slurper.parseText(new String(result.returnResult().body)).id then: assert greetingId }

@codeJENNerator

@codeJENNerator Spring REST Docs Gradle Conﬁguration dependencies { asciidoctor “org.springframework.restdocs:spring-restdocs-asciidoctor:${springRestDocsVersion}"
testCompile "org.springframework.restdocs:spring-restdocs-webtestclient:${springRestDocsVersion}" } ext { snippetsDir = "$buildDir/generated-snippets" } test { outputs.dir snippetsDir } asciidoctor { inputs.dir snippetsDir dependsOn test } build { dependsOn asciidoctor }

@codeJENNerator Spring REST Docs Gradle Conﬁguration dependencies { asciidoctor “org.springframework.restdocs:spring-restdocs-asciidoctor:${springRestDocsVersion}"
testCompile "org.springframework.restdocs:spring-restdocs-webtestclient:${springRestDocsVersion}" } ext { snippetsDir = "$buildDir/generated-snippets" } test { outputs.dir snippetsDir } asciidoctor { inputs.dir snippetsDir dependsOn test } build { dependsOn asciidoctor } Or mockmvc or restassured

@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) .operationPreprocessors() .withRequestDefaults(prettyPrint()) .withResponseDefaults(prettyPrint())) .build() } } Spring REST Docs with WebTestClient (setup)

@codeJENNerator Spring REST Docs with WebTestClient (tests) void 'test and
document creating a greeting with a custom name'() { when: def result = this.webTestClient.post().uri('/') .contentType(MediaType.APPLICATION_JSON) .accept(MediaType.APPLICATION_JSON) .body(BodyInserters.fromObject('{"message": "Hello!"}')) .exchange() .expectStatus().isOk() .expectBody() .jsonPath('$.id').isNotEmpty() .jsonPath('$.message').isEqualTo('Hello!') .consumeWith(document('greetings-post-example', requestFields( fieldWithPath('message') .type(JsonFieldType.STRING) .description("The greeting's message")))) JsonSlurper slurper = new JsonSlurper() greetingId = slurper.parseText(new String(result.returnResult().body)).id then: assert greetingId }

@codeJENNerator

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

@codeJENNerator +

@codeJENNerator [[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[] Adding The Snippets

@codeJENNerator

Publishing Strategies

@codeJENNerator • 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 Publishing Strategies

@codeJENNerator

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

@codeJENNerator Publish to GitHub Pages In build.gradle: plugins { id
'org.ajoberstar.git-publish' version '2.0.0' } In publish.gradle: gitPublish { repoUri = '[email protected]:jlstrater/groovy-spring-boot-restdocs-example.git' branch = 'gh-pages' contents { from file('build/asciidoc/html5') } commitMessage = 'Updating the doc example' }

@codeJENNerator Publish to GitHub Pages In build.gradle: plugins { id
'org.ajoberstar.git-publish' version '2.0.0' } In publish.gradle: gitPublish { repoUri = '[email protected]:jlstrater/groovy-spring-boot-restdocs-example.git' branch = 'gh-pages' contents { from file('build/asciidoc/html5') } commitMessage = 'Updating the doc example' } If you use this method, remember to deploy docs at the same time as the project!

@codeJENNerator

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

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

@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 Support for Rest-Assured

@codeJENNerator

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

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

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  }  } } Groovier Spring REST Docs Example - Ratpack Get a book by ISBN /api/books/1932394842

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  }  } } Groovier Spring REST Docs Example - Ratpack Get a book by ISBN /api/books/1932394842 Get all books /api/books

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  }  } } Groovier Spring REST Docs Example - Ratpack Get a book by ISBN /api/books/1932394842 Get all books /api/books Post to create a new book /api/books

@codeJENNerator 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 • https://jennstrater.blogspot.com/2017/01/using-spring- rest-docs-to-document.html • Blog Post https://jennstrater.blogspot.com/2017/01/using-spring- rest-docs-to-document.html

@codeJENNerator Related Tools & Libraries

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

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

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

@codeJENNerator Stubs

@codeJENNerator https://github.com/fbenz/restdocs-to-postman

@codeJENNerator

@codeJENNerator Spring REST Docs API speciﬁcation Integration or or

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

@codeJENNerator Outcomes

@codeJENNerator • Made it to production! (in 2016) • At
the time, the team was happy with Spring REST Docs • Other dev teams like to see the examples Outcomes

@codeJENNerator Next Steps

@codeJENNerator Join #spring-restdocs on gitter https://gitter.im/spring- projects/spring-restdocs Join the Groovy
Community on Slack groovycommunity.com Slides: https://speakerdeck.com/jlstrater/test-driven-docs- javaland-2019 Example Project: https://github.com/jlstrater/groovy- spring-boot-restdocs-example

Conclusion

@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 boilerplate documentation, but at least it’s a little less painful now. Conclusion

w Thank You @codeJENNerator

test driven docs javaland 2019

test driven docs javaland 2019

More Decks by jlstrater

Other Decks in Technology

Featured

Transcript