The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability

Transcription

1 The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability Steven Willmott CEO, 3scale Inc.

2 Credits Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar (Smartbear) and myself 2

3 Who Am I? CEO of 3scale Leading API Infrastructure Provider 700+ Customers Billions of API Calls Managed Early Swagger supporter Now OAI Founding Member 3

4 Introduction & Agenda OpenAPISpecification (OAS) Open API Initiative (OAI) Usage and Tooling Examples 4

5 The OpenAPI Specification fka the Swagger specification DRAFT - Open API Initiative (OAI) 5

6 What is the OpenAPI Specification? Generally Categorized REST API Description Language More Generally IDL for REST APIs 6

7 What does the OpenAPI Specification Offer? A simple format for writing REST service contracts Are independent from language, development framework, deployment technology Language Neutral & Machine Readable Format APIs can be defined in JSON or YAML API-First & Code-First Development 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 Comprehensive Tooling Support (core, UI, codegen, editor) Powerful Extension Mechanism 7

8 Road to the OAS 2010 Tony founded Swagger Development, Growth, Adoption, Tooling, Community Q Swagger acquired by SmartBear Q Linux Foundation Workgroup Forms Q Swagger renamed OpenAPI Specification 8

9 Adoption & Growth Most Popular API Framework 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 9

10 Community DRAFT - Open API Initiative 10 December

11 Broad Industry Adoption 11

12 Why adopt the OpenAPI Specification? Superior Tooling Best Industry Support Simple & Pragmatic Commitment to Remain Open Portable Vendor Neutral Community Strong Independent Sponsorship 12

13 The Importance of API Interface Definitions 13

14 What about Rest Interfaces? 14

15 REST API Development Evolution What Spec? Code is Spec Spec Generates Code Spec as Code 15

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 In your organization: inter-team dependencies Across the public Internet: crossorganization discovery & contracts Photo: Josh Hibbert / Unsplash.com 16

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: 20

21 OAI Governance Structure Business Governance Board (BGB) Budget, marketing, community, etc Technical Developer Community (TDC) Manages the OpenAPI Specification Technical Oversight Board (TOB) Resolves conflict in TDC 21

22 Swagger OpenAPI Specification (OAS) Moved from swagger-api 2.0 to OAI GitHub Repository 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 Documentatio n Structure Protocols and Payloads JSON Schema & JSON References URI Support Error Handling/Docu mentation Security Request Parameters Aiming for 2016 summer release ~mid July 23

24 OAS Usage Examples 24

25 Code First with Swagger Annotations 25

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 26

27 API First with Swagger Editor Lifecycle Tooling Wrapped Swagger Editor Manage API Metadata Governance & Review Dynamic Mock Responses 27

28 And Finally 28

29 Get Involved! Website: Spec: 29

30 Additional Information 30

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 31

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' 32

33 From Legacy Java Framework to Polyglot Microservices using & Servlet Filters X-Extensions 33