Tweet
Tweet

Slide 1

Slide 1 text

OpenAPI and Java Sean Sullivan Portland Java User Group December 10, 2019

Slide 2

Slide 2 text

About me software engineer Portland Oregon Java Scala

Slide 3

Slide 3 text

Agenda OpenAPI Real world examples Java tools and libraries API guidelines

Slide 4

Slide 4 text

OpenAPI

Slide 5

Slide 5 text

OpenAPI is a specification for describing API’s

Slide 6

Slide 6 text

API specifications

Slide 7

Slide 7 text

WSDL (SOAP) WADL (REST)

Slide 8

Slide 8 text

Swagger (REST) OpenAPI (REST)

Slide 9

Slide 9 text

https://en.wikipedia.org/wiki/OpenAPI_Specification

Slide 10

Slide 10 text

REST API’s

Slide 11

Slide 11 text

API Driven Development

Slide 12

Slide 12 text

“API first”

Slide 13

Slide 13 text

source: Adobe Tech Blog June 2017

Slide 14

Slide 14 text

Code first vs API schema first

Slide 15

Slide 15 text

JSON or YAML

Slide 16

Slide 16 text

Real world examples

Slide 17

Slide 17 text

Case Study: stripe.com OpenAPI

Slide 18

Slide 18 text

https://github.com/stripe/openapi

Slide 19

Slide 19 text

https://github.com/stripe/openapi

Slide 20

Slide 20 text

Case Study: squareup.com OpenAPI

Slide 21

Slide 21 text

https://github.com/square/connect-api-specification

Slide 22

Slide 22 text

Case Study: Kubernetes OpenAPI

Slide 23

Slide 23 text

https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec

Slide 24

Slide 24 text

https://github.com/kubernetes-client/java Kubernetes Java Client

Slide 25

Slide 25 text

https://github.com/kubernetes-client/java Kubernetes Java Client code generation

Slide 26

Slide 26 text

Case Study: Microsoft Azure OpenAPI

Slide 27

Slide 27 text

https://github.com/Azure/azure-rest-api-specs azure-rest-api-specs

Slide 28

Slide 28 text

Case Study: Amazon EventBridge OpenAPI

Slide 29

Slide 29 text

https://docs.aws.amazon.com/eventbridge Amazon EventBridge “EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources”

Slide 30

Slide 30 text

https://docs.aws.amazon.com/eventbridge EventBridge Schema Registry Schemas are defined using JSON files, using the OpenAPI specification

Slide 31

Slide 31 text

https://www.tbray.org/ongoing/When/201x/2019/12/02/Strongly-Typed-Events Strongly typed events

Slide 32

Slide 32 text

Java tools and libraries

Slide 33

Slide 33 text

Swagger libraries swagger-core swagger-parser swagger-codegen swagger-inflector

Slide 34

Slide 34 text

https://github.com/swagger-api/swagger-parser Swagger parser

Slide 35

Slide 35 text

pom.xml io.swagger.parser.v3 swagger-parser 2.0.16 Swagger parser

Slide 36

Slide 36 text

https://github.com/swagger-api/swagger-parser import io.swagger.v3.parser.OpenAPIV3Parser; import io.swagger.v3.oas.models.OpenAPI; String url = “http://petstore.swagger.io/v3/openapi.json”; OpenAPI openAPI = new OpenAPIV3Parser().read(url); Swagger parser

Slide 37

Slide 37 text

https://github.com/swagger-api/swagger-parser Swagger parser Pull Request #1271

Slide 38

Slide 38 text

ObjectMapperFactory.java return new JsonFactoryBuilder() .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION) .build(); Swagger parser Pull Request #1271

Slide 39

Slide 39 text

Code generators Guardrail openapi-generator swagger-codegen AutoRest

Slide 40

Slide 40 text

Guardrail project

Slide 41

Slide 41 text

https://guardrail.dev/ Guardrail

Slide 42

Slide 42 text

https://github.com/twilio/guardrail Guardrail

Slide 43

Slide 43 text

https://github.com/twilio/guardrail Guardrail: Scala ScalaMeta

Slide 44

Slide 44 text

https://github.com/twilio/guardrail Guardrail: Java JavaParser

Slide 45

Slide 45 text

Guardrail example

Slide 46

Slide 46 text

guardrail-maven-plugin com.twilio guardrail-maven-plugin_2.12 0.54.5 …

Slide 47

Slide 47 text

guardrail-maven-plugin java client dropwizard ${project.basedir}/src/main/openapi/petstore.json com.example.clients.petstore Java client

Slide 48

Slide 48 text

guardrail-maven-plugin

Slide 49

Slide 49 text

openapi-generator project

Slide 50

Slide 50 text

openapi-generator

Slide 51

Slide 51 text

openapi-generator

Slide 52

Slide 52 text

openapi-generator

Slide 53

Slide 53 text

REST API guidelines

Slide 54

Slide 54 text

https://github.com/microsoft/api-guidelines

Slide 55

Slide 55 text

https://www.infoq.com/news/2016/07/microsoft-rest-api/ July 2016

Slide 56

Slide 56 text

https://cloud.google.com/apis/design/

Slide 57

Slide 57 text

https://github.com/zalando/restful-api-guidelines

Slide 58

Slide 58 text

https://github.com/paypal/api-standards/blob/master/api-style-guide.md

Slide 59

Slide 59 text

Final thoughts use OpenAPI to define REST API’s adopt “API First” approach use a code generator to generate client libraries contribute to open source projects

Slide 60

Slide 60 text

The End