The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability
Download as PPTX, PDF5 likes3,046 views
This document discusses the evolution of the OpenAPI Specification (formerly known as the Swagger specification) and the formation of the Open API Initiative. It provides an overview of the OpenAPI Specification and how it offers a standard way to define REST APIs. It also outlines how the specification has been adopted broadly and the importance of having a common definition for REST APIs.
The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability
- 1. The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability Steven Willmott CEO, 3scale Inc. [email protected] : @njyx
- 2. Credits 2 ▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar (Smartbear) and myself ▪ http://openapis.org/
- 3. Who Am I? ▪ http://www.3scale.net ▪ @3scale ▪ Early Swagger supporter ▪ Now OAI Founding Member 3 ▪ CEO of 3scale ▪ Leading API Infrastructure Provider ▪ 700+ Customers ▪ Billions of API Calls Managed
- 4. Introduction & Agenda 4 ▪ OpenAPI Specification (OAS) ▪ Open API Initiative (OAI) ▪ Usage and Tooling Examples
- 5. The OpenAPI Specification fka “the Swagger specification” DRAFT - Open API Initiative (OAI) 5
- 6. What is the OpenAPI Specification? 6 Generally Categorized REST API Description Language More Generally IDL for REST APIs
- 7. What does the OpenAPI Specification Offer? 7 A simple format for writing REST service contracts ▪ Are independent from language, development framework, deployment technology ▪ Can be expressed in YAML or JSON format ▪ Support both API-first and code-first approaches to defining, building and documenting APIs ▪ Have a clean & powerful extension mechanism Language Neutral & Machine Readable Format APIs can be defined in JSON or YAML API-First & Code-First Development Powerful Extension Mechanism Comprehensive Tooling Support (core, UI, codegen, editor)
- 8. Road to the OAS 8 2010 Tony Tam @Wordnik founded Swagger Q1 2015 Swagger acquired by SmartBear Q3 2015 Linux Foundation Workgroup Forms Q4 2015 Swagger renamed “OpenAPI Specification” 2010 - 2014 Development, Growth, Adoption, Tooling, Community
- 9. Adoption & Growth 9 ▪ 100,000 weekly source visits ▪ 11,500 daily downloads ▪ 10,000 daily visitors to swagger.io ▪ 4,600 forks of official repos ▪ 1,700 public repos on GitHub ▪ Client/server support in all popular languages & frameworks Most Popular API Framework
- 10. Community 10 December 2014DRAFT - Open API Initiative 10
- 12. Why adopt the OpenAPI Specification? 12 Commitment to Remain Open Portable Vendor Neutral Strong Independent Sponsorship CommunitySimple & Pragmatic Superior Tooling Best Industry Support
- 13. The Importance of API Interface Definitions 13
- 14. 14 What about Rest Interfaces?
- 15. 15 What Spec? Spec Generates Code Spec as Code Code is Spec REST API Development Evolution
- 16. Shared Definitions are Crucial ▪ Stable Interface Definition ▪ Managed process around change ▪ Discovery of capabilities ▪ Automation of processes and procedures ▪ Essential at 100’s APIs ▪ Invaluable at 10’s Thousands and Millions 16Photo: Josh Hibbert / Unsplash.com In your organization: inter-team dependencies Across the public Internet: cross- organization discovery & contracts
- 17. Shared Definitions are Crucial ▪ Fixed point of Reference ▪ Automation: ▪ Explorers / Docs ▪ Code Gen ▪ Editors ▪ Search ▪ Testing ▪ Change Management ▪ Management platforms ▪ Design Focus 17
- 18. The Open API Initiative 18
- 19. The Open API Initiative - Mission Provide an open source, technical community, within which industry participants may easily contribute to building a vendor-neutral, portable and open specification for providing technical metadata for REST APIs – The OpenAPI Specification. 19
- 20. OAI Initial Steps ▪ Establishment of a clear, open governance structure for both business & technical direction ▪Swagger specification donated to the Open API Initiative ▪ Meritocratic approach to technical contributions – not pay-to-play ▪ Charter is here: https://openapis.org/governance 20
- 21. OAI Governance Structure 21 Business Governance Board (BGB) Budget, marketing, community, etc… Technical Developer Community (TDC) Manages the OpenAPI Specification Technical Oversight Board (TOB) Resolves conflict in TDC
- 22. Swagger ➔ OpenAPI Specification (OAS) ▪ Moved from swagger-api 2.0 to OAI GitHub Repository ▪ https://github.com/oai/OpenAPI-Specification ▪ Core TDC elected and working on next version 3.0 of spec ▪ Apache 2.0 License as before ▪ You can/should join the discussion – please do! 22
- 23. Focus of OpenAPI Spec 3.0 Aiming for 2016 summer release ~mid July 23 Documentatio n Structure Protocols and Payloads JSON Schema & JSON References URI Support Error Handling/Docu mentation Security Request Parameters
- 25. 25 Code First with Swagger Annotations
- 26. 26 Swagger UI Build docs by processing JSON/YAML API Spec The API Spec can be returned from static source or from the running API
- 27. 27 API First with Swagger Editor Wrapped Swagger Editor Lifecycle Tooling Manage API Metadata Governance & Review Dynamic Mock Responses
- 28. And Finally… 28
- 29. Get Involved! Website: https://openapis.org/ Spec: https://github.com/oai Follow: @OpenApiSpec 29
- 31. 31 OpenAPI Spec’s X-Extensions Additional data added to API definition to extend the specification Always prefixed by "x-" and can have any valid JSON/YAML format value
- 32. 32 OpenAPI Spec’s X-Extensions paths: /demo/bankthings: get: summary: Returns a list of Bank Things operationId: getBankThings x-c1-proxy: audit parameters: - $ref: '#/parameters/ApiKey'
- 33. 33 From Legacy Java Framework to Polyglot Microservices using OpenAPI @Annotations & Servlet Filters ➔ X-Extensions