Dennis Kieselhorst presents the evolution of the OpenAPI Specification (OAS) from its origins in Swagger, emphasizing the transition from version 2.0 to 3.0.x and the development of the OpenAPI Initiative in 2015. The document discusses the importance of tooling support and asynchronous use cases, along with examples of API creation automation. OAS 3.0.x is positioned to eventually replace Swagger 2.0, with major industry players actively involved in its development.

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