WSO2Con - OpenAPI Specification 3 - the evolution of Swagger

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 talk will show 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.

Transcript

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. 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
12. Livedemo
13. Automate API creation in a CI pipeline source: Jenkins User documentation
14. 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
15. • 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
16. THANK YOU wso2.com