This document summarizes a presentation about designing, auto-generating, and exposing RESTful microservices using OpenAPI (formerly known as Swagger) and WebSphere. The presentation covers an introduction to OpenAPI, designing RESTful APIs using OpenAPI, generating server-side and client-side code from OpenAPI specifications, and deployment options. The presenters are Tim deBoer from IBM and Arthur De Magalhaes from IBM.

1. InterConnect
2017
BAS-2030
Design, Auto-Generate and
Expose RESTful Microservices
Using Open Source and
WebSphere
Tim deBoer,
Arthur De Magalhaes
WebSphere Development
1 3/17/17

2. Tim deBoer
WebSphere developer experience lead
deboer@ca.ibm.com
Arthur De Magalhaes
WebSphere REST API architect
arthurdm@ca.ibm.com
2 3/17/17
Who are we?

3. 3 3/17/17
Agenda
• A brief intro to Swagger
• Designing RESTful API using Swagger
• Generating server-side code
• Generating client-side code
• Deployment Options
• Q/A

4. Swagger
4 3/17/17

5. 5 3/17/17
What is Swagger?
The industry-leading specification for defining REST APIs
Defined via JSON or YAML files (a “Swagger doc”)
Swagger is:
• API documentation (or at least the metadata for it)
• The contract between producer and consumer
• The metadata needed to generate client code, server stubs, tests, ….

6. 6 3/17/17
What is Swagger?
• 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 repository, with 15000 daily downloads
• Base specification for the OpenAPI Initiative (https://openapis.org/), under
Linux foundation

7. 7 3/17/17
Why API-first?
Swagger can be used to document or expand existing services, but starting
with Swagger for new services has a number of benefits:
• Clean API (design what you want, not document what you’ve built)
• Usable/useful API (easier for consumers to provide input up front)
• Allows producer and consumers to begin work independently
• Lends itself to enforcing modeling and security standards
• Fits naturally with a central API catalog

8. Designing
RESTful API
8 3/17/17

9. 9 3/17/17
Designing REST APIs
• Lots of options! We’ll look at:
• Swagger Online Editor
• SwaggerHub
• WebSphere Developer Tools
• API Connect
• Attributes to consider depend on design scenario
• Validation, code generation, lifecycle management, publishing, etc

10. 10 3/17/17
Swagger Online Editor
http://editor.swagger.io/

11. 11 3/17/17
SwaggerHub
https://app.swaggerhub.com

12. 12 3/17/17
WebSphere Developer Tools

13. 13 3/17/17
API Connect Editor
https://console.ng.bluemix.net/apis/apiconnect

14. 14 3/17/17
API Connect Developer Toolkit
npm –g install apiconnect

15. • API Connect editor
• Developer portal
15 3/17/17
Demo

16. Generating
Services
From Swagger
16 3/17/17

17. There are many options for generating
server-side code from Swagger:
• Liberty App Accelerator
• Swagger Online Editor
• WebSphere Developer Tools
All of these are based on the same
open-source code generation
17 3/17/17
Server-side Code Generation

18. The apiDiscovery-1.0 feature
adds Swagger support to Liberty:
• Swagger auto-generated
from JAX-RS and/or picked
up from Swagger file in app
• Built-in API Explorer for
discovering & unit testing
API
18 3/17/17
Swagger in Liberty

19. The API Explorer can be used to
self-document a service
• Customize branding
• CSS from designers
19 3/17/17
The Self-Documenting Service

20. • Generate server-side code
• Add implementation
• Add apiDiscovery-1.0
• API Explorer unit testing
• Add branding
20 3/17/17
Demo

21. Generating
Clients
21 3/17/17

22. 22 3/17/17
Client generation
• Two main use cases:
• Tests from Q/A team (multiple languages)
• Enhancing server-side code (same language)
• Advantages of using a generated client vs building your own:
• Collaborate with and benefit from open source community
• Test with code that your customers are using
• Standardize code across your company

23. 23 3/17/17
Swagger Client Generator Jar
• https://github.com/swagger-api/swagger-codegen
• brew install swagger-codegen

24. 24 3/17/17
Swagger Client Generator UI
https://generator.swagger.io/

25. 25 3/17/17
WDT JAX-RS Client Generator
Available in the Eclipse marketplace

26. • Swagger online editor
26 3/17/17
Demo

27. Deploying
RESTful Microservices
27 3/17/17

28. Deployment Platforms
linux
windows
aix
solaris hp/ux
z/linux
z/os
ibm-i
mac/osx
WebSphere
Application
ServerICS
Cloud
Foundry
local
dedicated
public
Private IaaS
WAS Patterns
Pure App System
Public IaaS
IBM Softlayer
MS Azure
Amazon AWS
Other
PaaS
private
OpenShift
Cloud
Foundry

29. 29
Let’s collaborate!
websphereconnect.slack.com
github.com/microservices-api
-- github.com/microservices-api/websphere-connect/wiki
Email for invitation (or drop off business card): arthurdm@ca.ibm.com

30. Upcoming sessions
• The Open API Initiative at Twelve Months and Counting
• Tuesday, 1:30 PM - 2:15 PM | South Pacific J | Session ID: 5968A
• Meet the Expert on Connecting to the IBM Cloud
• Wednesday, 1:00 PM - 1:45 PM | Meet the Experts Forum # 1 | Session ID: 7083A
• Connect Your WebSphere Environment to the Cloud with IBM WebSphere Connect
• Wednesday, 3:15 PM - 3:35 PM | Engagement Theater Booth #319 | Session ID: 7234A
• Learn How to Connect Microservices Using the Open API Initiative
• Thursday, 11:30 AM - 12:15 PM | Surf D | Session ID: 2611A

31. 31
Notices and disclaimers
Copyright © 2017 by International Business Machines Corporation (IBM).
No part of this document may be reproduced or transmitted in any form
without written permission from IBM.
U.S. Government Users Restricted Rights — use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM.
Information in these presentations (including information relating to
products that have not yet been announced by IBM) has been reviewed
for accuracy as of the date of initial publication and could include
unintentional technical or typographical errors. IBM shall have no
responsibility to update this information. This document is distributed
“as is” without any warranty, either express or implied. In no event
shall IBM be liable for any damage arising from the use of this
information, including but not limited to, loss of data, business
interruption, loss of profit or loss of opportunity. IBM products and
services are warranted according to the terms and conditions of the
agreements under which they are provided.
IBM products are manufactured from new parts or new and used parts.
In some cases, a product may not be new and may have been previously
installed. Regardless, our warranty terms apply.”
Any statements regarding IBM's future direction, intent or product
plans are subject to change or withdrawal without notice.
Performance data contained herein was generally obtained in a
controlled, isolated environments. Customer examples are presented
as illustrations of how those customers have used IBM products and
the results they may have achieved. Actual performance, cost, savings or
other results in other operating environments may vary.
References in this document to IBM products, programs, or services
does not imply that IBM intends to make such products, programs or
services available in all countries in which IBM operates or does
business.
Workshops, sessions and associated materials may have been prepared
by independent session speakers, and do not necessarily reflect the
views of IBM. All materials and discussions are provided for informational
purposes only, and are neither intended to, nor shall constitute legal or
other guidance or advice to any individual participant or their specific
situation.
It is the customer’s responsibility to insure its own compliance with legal
requirements and to obtain advice of competent legal counsel as to
the identification and interpretation of any relevant laws and regulatory
requirements that may affect the customer’s business and any actions
the customer may need to take to comply with such laws. IBM does not
provide legal advice or represent or warrant that its services or products
will ensure that the customer is in compliance with any law.

32. 32
Notices and disclaimers
continued
Information concerning non-IBM products was obtained from the
suppliers of those products, their published announcements or other
publicly available sources. IBM has not tested those products in
connection with this publication and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be
addressed to the suppliers of those products. IBM does not warrant the
quality of any third-party products, or the ability of any such third-party
products to interoperate with IBM’s products. IBM expressly disclaims
all warranties, expressed or implied, including but not limited to, the
implied warranties of merchantability and fitness for a particular,
purpose.
The provision of the information contained herein is not intended to, and
does not, grant any right or license under any IBM patents, copyrights,
trademarks or other intellectual property right.
IBM, the IBM logo, ibm.com, Aspera®, Bluemix, Blueworks Live, CICS,
Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document
Management System™, FASP®, FileNet®, Global Business Services®,
Global Technology Services®, IBM ExperienceOne™, IBM SmartCloud®,
IBM Social Business®, Information on Demand, ILOG, Maximo®,
MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower,
PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®,
PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®,
PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®,
SoDA, SPSS, Sterling Commerce®, StoredIQ, Tealeaf®, Tivoli® Trusteer®,
Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and
System z® Z/OS, are trademarks of International Business Machines
Corporation, registered in many jurisdictions worldwide. Other product
and service names might be trademarks of IBM or other companies. A
current list of IBM trademarks is available on the Web at "Copyright and
trademark information" at: www.ibm.com/legal/copytrade.shtml.

33. InterConnect
2017
33