Swagger is the de facto standard for API description. It has evolved into a new version specified by the Open API Initiative under the umbrella of the Linux Foundation. This presentation explores improvements and new features that will help you to define even better APIs. A sample using Apache CXF, Spring Boot and WSO2 API Manager illustrates the benefits of implementing OpenAPI Specification 3.

1. Team Leader & Chief Architect Tixx
OpenAPI Specification 3:
The Evolution of Swagger
Dennis Kieselhorst

2. ● 15 years experience with distributed
software architectures
● worked as lead developer, architect and
consultant
● now team leader and chief architect Tixx
at CTS EVENTIM
● committer at Apache Software Foundation
● member of organizing committees
○ Java User Group (JUG) Bremen-Oldenburg
○ Java Forum Nord Hanover
About me
source: Pixabay geralt

3. ● the glue between applications
● described with Web Services Description Language (WSDL) in
the past but not resource-oriented
● Web Application Description Language (WADL) is
resource-oriented but has cumbersome XML-structure
● that's why Swagger was born in 2010 as an interface
definition language (IDL) for REST-APIs
Application Programming Interfaces (APIs)
source: Pixabay geralt

4. ● fast-growing Swagger fan community
● bought by SmartBear in early 2015
● formation of the Open API Initiative (OAI) under the umbrella
of the Linux Foundation by the end of 2015
○ now counts 33 members including Google, Microsoft and WSO2.
● Swagger was renamed to OpenAPI Specification (OAS)
○ old name is still used for tooling
○ further spec development happens on GitHub
○ in July 2017 the new major version 3.0.0 was published, followed by
3.0.1 in December 2017 and 3.0.2 in October 2018
Formation of the Open API Initiative
source: Pixabay congerdesign

5. Differences between version 2.0 and 3.0.x
source: Darrel Miller Open API Initiative

6. source: Darrel Miller Open API Initiative

7. source: Darrel Miller Open API Initiative

8. source: Darrel Miller Open API Initiative

9. ● Alternative schemas like Google Protocol Buffers are in
discussion, but not yet integrated in the specification.
● Asynchronous use cases like MQTT and AMQP are part of
the AsyncAPI Specification that is based on the OpenAPI
specification
Not covered by the current spec
source: Pixabay wilhei

10. ● Swagger tooling
○ a core library (swagger-core),
○ a UI for visualization and test calls (swagger-ui),
○ a code generator (swagger-codegen) as well as
○ an editor (swagger-editor)
● MicroProfile OpenAPI implemented by Open
Liberty and WildFly Swarm/ Thorntail
● Apache CXF
● ...
Tool support for OpenAPI development
source: Pexels startupstockphotos.com

11. alternatively download the CXF sourcecode distribution
Sample: Hello Demo with CXF and Spring Boot
git clone https://github.com/apache/cxf
cd distribution/src/main/release/samples/jax_rs/spring_boot
mvn spring-boot:run
x-www-browser http://localhost:8080/services/helloservice/
api-docs?url=/services/helloservice/openapi.json
source: Pexels Markus Spiske

12. download the CXF sourcecode distribution for more samples
Sample: Petstore with CXF and Spring Boot
git clone https://github.com/deki/swagger-samples/ --branch
java-cxf-spring-boot-minimal
cd java/java-cxf-spring-boot-minimal
mvn spring-boot:run
x-www-browser
http://localhost:8080/services/api-docs?url=/services/openapi.yaml
source: Pexels Markus Spiske

13. Livedemo

14. Automate API creation in a CI pipeline
source: Jenkins User documentation

15. see WSO2 API-Manager RESTful API docs for more details
Automate API creation in WSO2 API-Manager
curl -k -d
"grant_type=password&username=admin&password=admin&scope=apim:api
_create" -H "Authorization: Basic ABC....."
https://localhost:8243/token
curl -k
-H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
-H "Content-Type: application/json"
-X POST
-d @data.json
https://localhost:9443/api/am/publisher/v0.14/apis
source: Pexels Markus Spiske
Livedemo

16. ● Swagger 2.0 is a de facto standard
○ widely used in REST-based applications
○ extensive tool-support
● OpenAPI Specification 3.0.x is a reasoned cleanup
○ all famous vendors are part of the initiative
○ will replace Swagger 2.0 as soon as all common tools have adapted
OAS 3.0.x
○ WSO2 API-Manager already supports OAS 3.0.0
Conclusion
source: Huw Williams

17. THANK YOU
wso2.com