Tweet
Tweet

Slide 1

Slide 1 text

Preparing for the future of API Description Languages @kylefuller © Oracle Corpora,on UK Limited, 2018 1

Slide 2

Slide 2 text

Preparing for the future of API Description Languages @kylefuller © Oracle Corpora,on UK Limited, 2018 2

Slide 3

Slide 3 text

© Oracle Corpora,on UK Limited, 2018 3

Slide 4

Slide 4 text

Agenda • Evolu'on of formats in Apiary • How we tackled suppor'ng mul'ple formats • Our plan for suppor'ng OAS 3 • Differences between Swagger 2 and OAS 3 © Oracle Corpora,on UK Limited, 2018 4

Slide 5

Slide 5 text

Apiary Blueprint 2012 - 2014 © Oracle Corpora,on UK Limited, 2018 5

Slide 6

Slide 6 text

API Blueprint 1 2014 - Present 1 h$ps:/ /apiblueprint.org © Oracle Corpora,on UK Limited, 2018 6

Slide 7

Slide 7 text

2 2 h$ps:/ /swagger.io © Oracle Corpora,on UK Limited, 2018 7

Slide 8

Slide 8 text

Apiary Product Surface © Oracle Corpora,on UK Limited, 2018 8

Slide 9

Slide 9 text

Apiary Editor © Oracle Corpora,on UK Limited, 2018 9

Slide 10

Slide 10 text

Interactive Documentation © Oracle Corpora,on UK Limited, 2018 10

Slide 11

Slide 11 text

Interactive Console © Oracle Corpora,on UK Limited, 2018 11

Slide 12

Slide 12 text

Traffic Inspector © Oracle Corpora,on UK Limited, 2018 12

Slide 13

Slide 13 text

Mock Server © Oracle Corpora,on UK Limited, 2018 13

Slide 14

Slide 14 text

Dredd © Oracle Corpora,on UK Limited, 2018 14

Slide 15

Slide 15 text

Dredd © Oracle Corpora,on UK Limited, 2018 15

Slide 16

Slide 16 text

API Style Guide © Oracle Corpora,on UK Limited, 2018 16

Slide 17

Slide 17 text

... and more © Oracle Corpora,on UK Limited, 2018 17

Slide 18

Slide 18 text

Abstract Format © Oracle Corpora,on UK Limited, 2018 18

Slide 19

Slide 19 text

Abstract Format © Oracle Corpora,on UK Limited, 2018 19

Slide 20

Slide 20 text

Abstract Format © Oracle Corpora,on UK Limited, 2018 20

Slide 21

Slide 21 text

Canonical API Description Format © Oracle Corpora,on UK Limited, 2018 21

Slide 22

Slide 22 text

API Elements © Oracle Corpora,on UK Limited, 2018 22

Slide 23

Slide 23 text

API Elements { "element": "httpResponse", "attributes": { "statusCode": { "element": "number", "content": 200 } }, "content": [...] } © Oracle Corpora,on UK Limited, 2018 23

Slide 24

Slide 24 text

API Elements { "element": "httpResponse", "attributes": { "statusCode": { "element": "number", "content": 200 } }, "content": [...] } © Oracle Corpora,on UK Limited, 2018 24

Slide 25

Slide 25 text

API Elements { "element": "string", "attributes": { "sourceMap": { "element": "sourceMap", "content": [5, 10] } }, "content": "Hello World" } © Oracle Corpora,on UK Limited, 2018 25

Slide 26

Slide 26 text

API Elements © Oracle Corpora,on UK Limited, 2018 26

Slide 27

Slide 27 text

API Elements (JS) © Oracle Corpora,on UK Limited, 2018 27

Slide 28

Slide 28 text

Adapters © Oracle Corpora,on UK Limited, 2018 28

Slide 29

Slide 29 text

Adapters © Oracle Corpora,on UK Limited, 2018 29

Slide 30

Slide 30 text

Process Involved in adding OAS 3 © Oracle Corpora,on UK Limited, 2018 30

Slide 31

Slide 31 text

© Oracle Corpora,on UK Limited, 2018 31

Slide 32

Slide 32 text

OAS 3: Focus • Structure Simplifica/on • Improved Re-usability © Oracle Corpora,on UK Limited, 2018 32

Slide 33

Slide 33 text

OAS 3: Changes • Swagger -> OpenAPI • GitHub-flavoured Markdown -> CommonMark • YAML • 2.0 -> 3.0 © Oracle Corpora,on UK Limited, 2018 33

Slide 34

Slide 34 text

OAS 3: JSON Schema • Larger JSON Schema support • oneOf, anyOf, not, and more • nullable (x-nullable extension in Swagger 2) © Oracle Corpora,on UK Limited, 2018 34

Slide 35

Slide 35 text

OAS 3: Content Negotiation © Oracle Corpora,on UK Limited, 2018 35

Slide 36

Slide 36 text

A Visual Guide to What's New in Swagger 3.0 4 4 h$ps:/ /blog.readme.io/an-example-filled-guide-to-swagger-3-2/ © Oracle Corpora,on UK Limited, 2018 36

Slide 37

Slide 37 text

A Visual Guide to What's New in Swagger 3.0 4 4 h$ps:/ /blog.readme.io/an-example-filled-guide-to-swagger-3-2/ © Oracle Corpora,on UK Limited, 2018 37

Slide 38

Slide 38 text

A Visual Guide to What's New in Swagger 3.0 4 4 h$ps:/ /blog.readme.io/an-example-filled-guide-to-swagger-3-2/ © Oracle Corpora,on UK Limited, 2018 38

Slide 39

Slide 39 text

A Visual Guide to What's New in Swagger 3.0 4 4 h$ps:/ /blog.readme.io/an-example-filled-guide-to-swagger-3-2/ © Oracle Corpora,on UK Limited, 2018 39

Slide 40

Slide 40 text

A Visual Guide to What's New in Swagger 3.0 4 4 h$ps:/ /blog.readme.io/an-example-filled-guide-to-swagger-3-2/ © Oracle Corpora,on UK Limited, 2018 40

Slide 41

Slide 41 text

OAS 3: Callbacks © Oracle Corpora,on UK Limited, 2018 41

Slide 42

Slide 42 text

OAS 3: Links © Oracle Corpora,on UK Limited, 2018 42

Slide 43

Slide 43 text

OAS 3 and API Elements © Oracle Corpora,on UK Limited, 2018 43

Slide 44

Slide 44 text

OAS 3 Adoption Plan © Oracle Corpora,on UK Limited, 2018 44

Slide 45

Slide 45 text

OAS 3: Phase 1 Soft Launch © Oracle Corpora,on UK Limited, 2018 45

Slide 46

Slide 46 text

OAS 3: Phase 2 Public Launch © Oracle Corpora,on UK Limited, 2018 46

Slide 47

Slide 47 text

OAS 3: Phase 3 Maturity © Oracle Corpora,on UK Limited, 2018 47

Slide 48

Slide 48 text

API Elements https://apielements.org © Oracle Corpora,on UK Limited, 2018 48

Slide 49

Slide 49 text

© Oracle Corpora,on UK Limited, 2018 49

Slide 50

Slide 50 text

@kylefuller [email protected] © Oracle Corpora,on UK Limited, 2018 50