@mrksdck

Design & Test First Workflow For REST APIs

How can REST API specification projects help us?

@mrksdck

“hand copy” workflow

designcodetestdocument

@mrksdck

“hand copy” workflow

design ≠ code ≠ test ≠ document

:(

@mrksdck

need for a better workflow

less error proneeasier specification implementation

specification can be changed

@mrksdck

REST API specification projects

api blueprint raml swagger

@mrksdck

helpful tools

designingcodingtesting

documenting

@mrksdck

designing

web - / text - editorssyntax highlighted

wysiwymvalidator

@mrksdck

coding

generateserverclient

models

@mrksdck

testing

write client & server testsvalidate implementation

import in tools e.g. postman

@mrksdck

documenting

dynamicstatic

@mrksdck

tools are here to help

→ generate test server→ generate test client→ code→ validate implementation→ document

@mrksdck

“tooled” workflow

designtestcodedocument

@mrksdck

“tooled” workflow

design = test = code = document

:)

@mrksdck

swagger as an example

swagger specswagger editor

swagger codegenswagger ui

@mrksdck

swagger spec

write in editorgenerate from annotated codeput into version control system

use as exchange document

@mrksdck

swagger spec

@mrksdck

swagger spec

@mrksdck

swagger editor

@mrksdck

@mrksdck

swagger codegen

possible targetsandroid, async-scala, csharp, dart, flash, java, jaxrs, inflector, nodejs, objc, perl, php, python, python3,

qt5cpp, retrofit, ruby, scala, scalatra, silex-PHP, sinatra, spring-mvc, dynamic-html, html, swagger, swagger-yaml,

swift, tizen, typescript-angular, typescript-node, akka-scala, CsharpDotNet2

@mrksdck

swagger codegen

implement generated interfacesuse generated clients in tests

get to know different frameworks

@mrksdck

swagger ui

reads swagger.jsondynamic html page

try out

@mrksdck

swagger ui

@mrksdck

swagger ui

@mrksdck

swagger ui

@mrksdck

swagger ui

@mrksdck

“tooled” workflow

designtestcodedocument

@mrksdck

artefact relations

design

test code document

@mrksdck

automation

design swagger-validationtestcode assertj-swaggerdocument swagger-codegen

@mrksdck

“tooled” workflow

design = test = code = document

:)

@mrksdck

“design and test first” - workflow

design = test = code = document

@mrksdck

Thank you for listening

Questions?

@mrksdck

References

examples are taken from swagger.iohttp://petstore.swagger.io/http://editor.swagger.io/http://github.com/swagger-api/

@mrksdck

related blog postshttp://swagger.io/writing-apis-with-the-swagger-inflector/http://blog.raml.org/guest-post-api-first-with-raml-development-and-documentation-of-rest-apis/