Going to Infinity and Beyond Documentation with OpenAPI Specification (Longhorn PHP Edition)

A presentation at Longhorn PHP in May 2019 in Austin, TX, USA by Taylor Barnett

Slide 1

Slide 1

Going to Infinity and Beyond Documentation with OpenAPI Specification

Slide 2

Slide 2

Person dreaming of self documenting APIs

Slide 3

Slide 3

Single Source of Truth

Slide 4

Slide 4

So you've built an API...

Slide 5

Slide 5

What is the OpenAPI Specification? (formerly known as Swagger)

Slide 6

Slide 6

Standard, structured approach for describing REST APIs that is both human and machine readable

Slide 7

Slide 7

Overview of the section of an OpenAPI document

Slide 8

Slide 8

An OpenAPI document looks like:

openapi: 3.0.0 info: version: 1.0.0 title: “Corgi API” (and it goes on…)

Slide 9

Slide 9

components: schemas: Corgi: required: (and it goes on…)

Slide 10

Slide 10

Lead Community Engineer at Stoplight

email -> taylor@stoplight.io twitter -> taylor_atx

Slide 11

Slide 11

Bridge with HTTP on it

Slide 12

Slide 12

Bridge with HTTP on it and humans written below

Slide 13

Slide 13

Hidden OpenAPI Benefits

Slide 14

Slide 14

It is NOT just for API References

Slide 15

Slide 15

  • Development contract
  • Prototype and mocking
  • Client libraries and SDKs
  • Testing
  • Server stubs

Slide 16

Slide 16

More than a technical representation

Slide 17

Slide 17

Tool for Collaboration

Slide 18

Slide 18

Simplifies Standardizes

Slide 19

Slide 19

Slide 20

Slide 20

Slide 21

Slide 21

Slide 22

Slide 22

Slide 23

Slide 23

Slide 24

Slide 24

Slide 25

Slide 25

Slide 26

Slide 26

Slide 27

Slide 27

Slide 28

Slide 28

Slide 29

Slide 29

Slide 30

Slide 30

Slide 31

Slide 31

Slide 32

Slide 32

Slide 33

Slide 33

Slide 34

Slide 34

Slide 35

Slide 35

Slide 36

Slide 36

Slide 37

Slide 37

Slide 38

Slide 38

Slide 39

Slide 39

Slide 40

Slide 40

Slide 41

Slide 41

Slide 42

Slide 42

Slide 43

Slide 43

Slide 44

Slide 44