This document provides an agenda and overview for a WebSphere Proof of Technology presentation on OpenAPI and APIs in WebSphere Liberty and the cloud. The presentation covers Swagger & WebSphere Connect, OpenAPI v3, APIs & Cloud, Open Liberty & MicroProfile, and introduces some labs. It discusses Swagger/OpenAPI specifications and tooling, API documentation and discovery in WebSphere Liberty, pushing APIs to IBM Cloud and containers, and collaborating on OpenAPI and MicroProfile standards.

1. WebSphere Proof of Technology
OpenAPI
Arthur De Magalhaes
API & Cloud Architect November 8, 2017

2. Agenda
• Swagger & WebSphere Connect
• OpenAPI v3
• APIs & Cloud
• Open Liberty & MicroProfile
• Labs Intro
1

3. WebSphere Proof of Technology
Swagger & WebSphere Connect

4. Swagger Introduction
• Industry leading specification for defining REST APIs.
• Supports both JSON and YAML formats.
• Large open source community with various projects on GitHub:
• Client code generation (37 languages)
• Server code generation (23 languages)
• Online editor and GUI
• Over 2000 related open-source repositories, with 15000 daily downloads
• Base specification for OpenAPI Initiative (https://openapis.org/),
under Linux foundation.

5. Swagger Annotations
• Documents the RESTful endpoint.
• Always in-sync, since it’s together with the code.

6. Swagger Yaml Example
5
paths:
/pet:
post:
summary: Add a new pet to the store
consumes: <mime type>
produces: <mime type>
parameters:
- in: body
name: body
description: Pet object that needs to be added to the store
required: true
schema: $ref: '#/definitions/Pet'
responses:
'405': description: Invalid input
security:
- petstore_auth:
- 'write:pets'

7. Hybrid
Cloud
Hybrid
Cloud
Hybrid
Cloud
WebSphere Connect is…
• A collection of capabilities built into WAS that help you turn backend WAS assets into APIs and
connect to and from the hybrid cloud to rapidly extend the value of their application investments
• WebSphere Application Server v8.5.5 and v9 (Liberty Core, Base, ND, z/OS) includes API Connect
Essentials as a Supporting Program, adding IBM Support and extra API calls per month
Business Assets
Supported by both Liberty and
traditional WAS
APIs
Get all the WebSphere Connect
capabilities with WAS v8.5.5 and
WAS v9
WebSphere Connect Overview

8. We want to change the way you think about constructing applications…
…leveraging not only an ecosystem of APIs, but also a rich
set of cloud-provided services…
…without having to perform significant re-engineering of
existing applications…
…whether they reside on-premises or in the cloud.
Why ”WebSphere Connect”?

9. WebSphere Liberty’s API Discovery apiDiscovery-1.0 feature

10. WebSphere Collective OpenAPI Support
• Adds dynamic routing and auto-scaling for Java and Node members
• Can be deployed inside Docker containers
• Aggregates OpenAPI for all clusters and collective members
Controller
Repository RESTM
OpenAPI from Members
M M M

11. JAXRS
Spec
1. Architect uses WDT or the Open Source online
Swagger editor to create new APIs.
2a: WDT and the App Accelerator are
capable of turning the Swagger
doc into server-side JAX-RS.
2c: The online editor is capable of
generating server-side JAX-RS
from the Swagger doc.
other editor
Design-first approaches

12. CI flow #1: manual pull of APIs after deployment
1. Git commit java or node code or dockerfile
5. APIs are now available in APIC’s developer portal
Deploy
2. Jenkins builds and packages apps & containers, and invokes UCD
3. UCD deploys artifacts onto collective
4. Admin imports APIs from WebSphere directly into APIC, manually
imports a committed product.yaml and then publishes both into a catalog.
M M
MM

13. CI flow #2: manual push of APIs after deployment
1. Git commit java or node code or dockerfile
6. APIs are now available in APIC’s developer portal
Deploy
2. Jenkins builds and packages apps & containers, and invokes UCD
3. UCD deploys artifacts onto collective
(on-prem, cloud, etc)
4. Admin invokes “curl POST /ibm/api/collective/docs/apiconnect,”
or uses the Swagger UI, sending a committed product.yaml as input.
5. Controller sends APIC the product.yaml and
swagger.yaml from each member, removing
duplicate APIs
M M
MM

14. WebSphere Proof of Technology
OpenAPI v3

15. • A simple, standard API description format
• Started by Swagger, specification donated to Linux Foundation
• Widely adopted, supported, vendor neutral
• Version 2 released 10/2014
• Version 3 released 07/2017
OpenAPI

16. OAI Members

17. OpenAPI V2 – V3
16
{
“openapi” : “3.0.0”,
“info” : {…},
“servers” : {…},
“paths” : {…},
“components” : {…},
“security” : {…},
“tags” : {…},
“externalDocs” : {…}
}

18. Servers
17
• Operations can override their own servers object

19. Servers - Variables
18

20. Components
19

21. Callbacks
20

22. Callbacks (2)
21

23. OpenAPI User Interface
• New UI: http://petstore.swagger.io/
22

24. https://github.com/swagger-api
apiDiscovery-1.0
Swagger 2.0
libs
OpenAPI 3.0
libs
openapi-3.0
Java 6 Java 8
Swagger UI Swagger UI
Liberty value-add Liberty value-add
stabilized current stream shared core UI
API support in WebSphere (Liberty 17.0.0.3)

25. WebSphere Proof of Technology
APIs & Cloud

26. 25
Bluemix is now IBM Cloud
https://www.ibm.com/blogs/bluemix/2017/10/bluemix-is-now-ibm-cloud/

27. IBM Cloud - Runtimes on CloudFoundry
Buildpacks
Boilerplates

28. IBM Cloud - Container Service

29. IBM Cloud – WAS on Cloud

30. 29
IBM Cloud Private http://ibm.biz/IBMCloudPrivate

31. • IBM Cloud allow server packages to be pushed.
• Creates an auto-discoverable container in the cloud.
Developer
Liberty buildpack
API Discovery on IBM Cloud
IBM Cloud | IBM Cloud Private

32. WebSphere Liberty Helm chart
31
github.com/IBM/charts

33. 32
• Call any Swagger REST API
• Enhance your app with value-adds
from a variety of microservices
• Add logic and deploy from within
the same eclipse instance.
Connect to cloud services

34. OpenAPI lifecycle
33

35. Hybrid cloud - via OpenAPI
Data Data
system APIsData
on-premises | local cloud
interaction APIs
private data cloud
app developers
public cloud
Data

36. WebSphere Proof of Technology
Open Liberty & MicroProfile

37. https://github.com/swagger-api
Swagger Spec
1.0, 1.1, 1.2, 2.0
27 OSS projects
Annotations, Parser, Codegen, UI, Node, etc
OpenAPI Spec 3.0
supports supports
OpenAPI v3 Community landscape

38. 37
Community Collaboration
• Stage 1: collaborate with SmartBear on Open Source annotations, parser,
converter, jaxrs, etc
• Stage 2: collaborate with Red Hat, SmartBear and MP community on plan for
including the Java programming model into MicroProfile

39. 38

40. 39
Open Liberty

41. 40
An Open Cloud Java Stack

42. 41
Let’s collaborate!
https://gitter.im/eclipse/microprofile-open-api
websphereconnect.slack.com email: arthurdm@ca.ibm.com
github.com/eclipse/microprofile-open-api
github.com/microservices-api
-- github.com/microservices-api/websphere-connect/wiki

43. WebSphere Proof of Technology
Labs Intro

44. Labs
• Lab 1: OpenAPI Support in WebSphere Liberty
– Create a Liberty Server and deploy a JAX-RS application
– Explore APIs using OpenAPI UI
– Examine JAX-RS application source including OpenAPI
annotations
• Lab 2: Push APIs to the Cloud
– Explore the Liberty Server package
– Push the server package to IBM Cloud
– Inspect the APIs in IBM Cloud
43

45. Labs
• Lab 3: OpenAPI Programming Models
– Understand OpenAPI Configuration and Builder
– Programmatically build APIs using OpenAPI Models
– Implement a custom OpenAPI Scanner
• Lab 4: A Design-First Approach to Building APIs
– Design APIs Using Swagger Editor
– Include the OpenAPI document within an application
– Explore the APIs
44

46. Bonus Content
• Bonus Lab: Converting Swagger 2.0 documents to
OpenAPI 3.0
– Explore SwaggerHub
– Explore changes from Swagger 2.0 to OpenAPI 3.0
• Open Liberty Guides
– Creating a RESTful web service
– Creating a MicroProfile application
45

47. Getting Started
• The Labs are available on GitHub
https://github.com/microservices-api/oas3-lab
• https://libertyswagger.mybluemix.net/api/explorer
• Local Resources
– /home/student/cascon/
– eclipse à (Contains eclipse with WDT plugin)
– wlp à (Liberty Server installation directory)
– OpenLiberty à (Open Liberty Guides)
– labs à (Draft version of labs – as backup) 46