OpenAPI 3.0, And What It Means for the Future of Swagger
12 likes9,607 views
The document discusses the OpenAPI 3.0 specification, detailing its new features, improvements in reusability, and structural changes from the previous version 2.0. It outlines the OpenAPI initiative's role in fostering a collaborative community for API design, documentation, and governance. The webinar covers the future of Swagger tools, including demonstrations and Q&A sessions.
OpenAPI 3.0, And What It Means for the Future of Swagger
- 1. 1 OpenAPI 3.0, And What It Means for the Future of Swagger
- 2. 2 Today’s Presenters Ole Lensmar CTO, SmartBear Software Chair, OpenAPI Initiative Ron Ratovsky Swagger Developer Evangelist, SmartBear Software Member, OpenAPI Technical Development Community
- 3. 3 Today’s Webinar Presented by SmartBear Software PLANNING DESIGN IMPLEMENT + TEST DEPLOY RETIRE eBOOKS WORKSHOPS DESIGN DOCUMENT CODE INTEGRATE FUNCTIONAL PERFORMANCE SECURITY VIRTUALIZATION MONITOR DEPLOY DEPRECATE VERSION TRAININGS CONFERENCES PARTNER INTEGRATIONS OPEN SOURCE OFFERINGS COMMERCIAL OFFERINGS
- 4. 4 Today’s Agenda • OpenAPI Initiative Overview • Why OAS 3.0 became the standard • What’s new in OAS 3.0 • OAS 3.0 in the API Lifecycle • What’s next for Swagger & SwaggerHub • Live Swagger demo • Q&A
- 6. 6 History of OpenAPI Initiative • Swagger Project founded in 2010 by Tony Tam / Reverb to design and document API interfaces • Groups large & small drawn to Project Interested in its simplicity, pragmatic approach, potential open governance • Acquired by SmartBear in early 2015 • Swagger 2.0 Spec donated by SmartBear Software to the Open API Initiative • OpenAPI Initiative reaches 27 members, including software providers and industry leaders in banking, healthcare, finance, & tech • OpenAPI 3.0 officially released on 7/26
- 7. 7 The OpenAPI Initiative 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 OAI is a collaborative project under the guidance of the The Linux Foundation. LF Projects use open source governance best practices, including license and contribution agreement choices, in keeping with the ideals of Linux.
- 8. 8 The OpenAPI Initiative - 2 main bodies • BGB - Provides governance for the OpenAPI Spec • Evangelization / Events / Sponsorships • Drives the APIStrat conference (new!) • Expertise & Knowledge Sharing • Licensing / Legal / Trademarks • Does not have any influence on the technical direction of the spec • TDC – Drives the evolution of the OpenAPI Spec • Drives the technical direction of the specification • Managed like any open-source project at https://github.com/OAI • Anyone is welcome and encouraged to join and suggest, discuss, ask and complain!
- 9. 9 What is the OpenAPI Specification? A common, public contract between services Independent of language, framework, deployment technology YAML or JSON format Supports both API-first and code-first approaches to defining, building and documenting APIs Bottom-up community and usage driven evolution
- 10. 10 Swagger? OpenAPI? OAS? OAI? Specification Tools
- 11. 1111 What’s New in OpenAPI 3.0?
- 12. 12 OAS 3.0 Specification Change Criteria • Clarity - The current "way" something is done doesn't make sense, is complicated, or not clear • Consistency - A portion of the specification is not consistent with the rest, or the industry standard terminology • Necessary functionality - We are missing functionality because of a certain design of the specification • Forward-looking designs - As usage of APIs evolves to new protocols, formats, patterns, we should always be considering what the next important functionality should be • Impact - A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec.
- 13. 13 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 14. 14 Specification Restructure and Improve Reusability OpenAPI 2.0 info host paths parameters security tags externalDocs basePath schemes securityDefinitions responses definitions produces consumes OpenAPI 3.0 info servers paths components security tags externalDocs
- 15. 15 Specification Restructured and Improve Reusability OpenAPI 3.0 Components schemas responses parameters examples requestBodies headers securitySchemes links callbacks - All reusable components are under one roof - Standardized naming - Added new objects for extended reusability
- 16. 16 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 17. 17 Improved parameter descriptions - New parameter type: cookie - Remove parameter types: body, formData - All parameters support complex types - Further serialization support by defining media types
- 18. 18 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 19. 19 Content Negotiation Support - Requests bodies and responses allow defining different schemas and examples for different media types - Improved file upload support - Responses support wildcard code definition - Eliminates `consumes` and `produces` from the spec
- 20. 20 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 21. 21 Support for Describing Callbacks - Allows definition of async APIs - Callbacks need to be implemented by both clients and servers - Callback URLs are expression based - Callbacks are defined by using the same structure as other path definitions
- 22. 22 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 23. 23 Introducing OpenAPI Links OpenAPI Links are Client-Computed, Design-Time Parameterized Traversals between Responses and Operations - Creation relations between responses and other operations - Parameters can depend on both the request and response - Client can follow links automatically - Depends on the API definition alone without runtime impact
- 24. 24 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 25. 25 Enhanced Examples - Examples can live in Parameters, Request Bodies, Responses and Schemas (*) - Examples can be reused - Additional Metadata - Name - Description - Can reference an external example
- 26. 26 So, What’s New in OAS 3.0? ✓ Improved reusability ✓ Parameter changes ✓ Content negotiation support ✓ Support for describing callbacks ✓ Links to express relationships between operations ✓ Improved examples ✓ Enhanced security definitions
- 27. 27 Enhanced Security Definitions - Renamed OAuth2 flows - Support for multiple flows - OpenID Connect support - ‘basic’ was replaced by ‘http’ - Supports different schemes and bearer formats
- 28. 28 OAS 3.0 – Additional Changes - CommonMark support in descriptions - Extended JSON Schema support - Multiple and templated server definitions - Support for TRACE method - No payload support for DELETE, GET…
- 29. 29 3.0 is a complete breaking change from 2.0 1. definitions, parameters, responses and securityDefinitions all moved under components 2. schemes, host, basePath have been replaced by servers 3. Parameters need to be restructured: - Type definitions move under schema - Body and formData parameters extracted to a requestBody 4. Responses need to be restructred: - ‘produces’media types moved to this level 5. Some security definition changes: - `basic` changed to `http` - OAuth2 flows renamed, given a slightly different structure
- 30. 3030 OAS 3.0 in the API Lifecycle
- 31. 31 Driving the API Lifecycle with OAS Design Implementation Testing Mocking Documentation Virtualization Deployment / Runtime Clients Security, Usage policies, Monitoring, Caching, etc Developer portals, Code samples, User guides, etc. Functional / Runtime simulations Functional, Security, Load, Compliance, etc. Generated server code/artifacts Prototyping Generated client libraries Object reuse, linking, Callbacks, etc.
- 32. 3232 What’s Next for Swagger?
- 33. 33 Swagger: The World’s Most Popular API Tooling for OpenAPI • 10 Million Downloads Worldwide • Combination of Swagger UI and Swagger Editor downloaded once every 3 seconds • SwaggerHub, launched 2015 – 60k API developers, architects, devops, technical writers, & managers use SwaggerHub to design & document APIs
- 34. 34 Built for OpenAPI Specification Swagger Editor Swagger UI Swagger Codegen HTML, Javascript, and CSS assets that dynamically generate documentation The first open source editor fully dedicated to OAS-based APIs. Turn your OAS definition into code, generating server stubs & client SDKs
- 35. 35 SwaggerHub: API Design & Documentation Platform SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow.
- 36. 36 Timeline of OAS 3.0 Support AUGUST • Swagger-UI/Editor ✓Editing/Viewing – out now! ▪ Sandbox functionality – end of August • Swagger-JS – end of August • Swagger-Core – mid August • Swagger-Parser – mid August • Swagger-Converter – end of August • Swagger-Inflector – end of August SEPTEMBER • Swagger-Validator – mid September • Swagger-Codegen – end of September • SwaggerHub – mid September
- 37. 3737 Let’s See It in Action
- 38. 38 Next Steps Additional Resources Swagger.io/docs/specification Learn Try Connect GitHub SwaggerAPI Twitter @SwaggerAPI Subscribe swagger.io/blog
- 39. 39 The Platform for Designing and Documenting APIs with Swagger Try SwaggerHub for Free www.swaggerhub.com