1.
GOING TO INFINITY AND Beyond
Documentation WITH OPENAPI
@TAYLOR_ATX

2.
HI! ! I'M THE LEAD COMMUNITY
ENGINEER AT Stoplight
FIND ME ON TWITTER @TAYLOR_ATX OR
TAYLOR@STOPLIGHT.IO

3.
SINGLE SOURCE OF
TRUTH
@taylor_atx

4.
SELF-DOCUMENTING APIS DO not EXIST
@taylor_atx

5.
WHAT IS OpenAPI
Specification?(FKA SWAGGER)
@taylor_atx

6.
STANDARD, structured approach FOR
DESCRIBING APIS THAT IS BOTH
human AND machine READABLE
@taylor_atx

7.
"OpenAPI is a bridge to understanding
and being able to communicate around
using HTTP as a transport, and our
greatest hope for helping [people] learn
their HTTPs and 123s."
-Kin Lane, API Evangelist
Photo by Jonas Verstuyft

8.
HIDDEN OPENAPI
BENEFITS ✨
@taylor_atx

9.
IT IS not JUST FOR API
REFERENCES !
@taylor_atx

10.
IT IS not JUST FOR API REFERENCES
▸ Development contract
▸ Prototyping and mocking
▸ Client SDKs and libraries
▸ Testing
▸ Server stubs
@taylor_atx

11.
YOU GET TO FOCUS ON
THE good stuff !
@taylor_atx

12.
TOOL FOR
Collaboration !
@taylor_atx

13.
TOOL FOR Collaboration
▸ Simplifies describing an API
▸ Standardizes terminology
▸ "API Fastness"
@taylor_atx

14.
ENHANCES Developer
Experience !
@taylor_atx

15.
ENHANCES Developer Experience
1. Design-First
2. Mocking and Feedback
3. Testing
@taylor_atx

16.
1. DESIGN-FIRST
@taylor_atx

17.
DESIGN-FIRST
▸ Consistency for users
▸ Important for critical APIs
▸ Code-first can be expensive
▸ Gain the benefits of using OpenAPI
@taylor_atx

18.
2. MOCKING AND
FEEDBACK
@taylor_atx

19.
WHY Should YOU CARE
ABOUT MOCKING?
@taylor_atx

20.
IF YOU WRITE DOCS, TUTORIALS, AND CONTENT, YOU CAN...
▸ Start writing sooner
▸ Give feedback
▸ Have more interactive docs
@taylor_atx

21.
IF YOU MAINTAIN CLIENT LIBRARIES OR SDKS, YOU CAN...
▸ More options
▸ Create libraries and SDKs faster
▸ Have libraries ready at release
@taylor_atx

22.
IF YOU CARE ABOUT DX, API DESIGN, ADVOCATE FOR USERS,
YOU CAN...
▸ Power feedback loops with mocking
▸ Put real endpoints in front of users
▸ Go look up "API Design Using Feedback Loops," by Lorinda Brandon
▸ "Experimental APIs"
@taylor_atx

23.
"Experimental APIs are mock services that use simulated
data to mimic API functions. They are designed with the
goal of getting early feedback from the community around
API desirability and design before the product release."
-Capital One DevExchange, "Design Thinking and API Design"
@taylor_atx

24.
MOCKING
▸ Start with humans
▸ "What are the tasks users want to accomplish?"
▸ "Will the API help them achieve these tasks?"
▸ "Are the endpoints confusing?"
@taylor_atx

25.
SOME OF THE COMPANIES WITH PUBLIC OPENAPI SPECIFICATIONS
ON GITHUB
SendGrid (16 contributors), Azure (440 contributors),
Slack, Stripe, NY Times, Flickr,
Box, Adafruit, Kubernetes, Nexmo,
Lufthansa, Netlify
@taylor_atx

26.
3. TESTING
@taylor_atx

27.
TESTING
▸ Gain the benefits of it being machine readable
▸ All kinds of validation testing
▸ Prioritize the experience
@taylor_atx

28.
CONTRACT TESTING
@taylor_atx

29.
CONTRACT TESTING
@taylor_atx

30.
LESS SUPPORT OVERHEAD
!
LESS CONFUSION AND HEADACHE
!
HAPPIER USERS (INCLUDING YOU!)
@taylor_atx

31.
THE REALITY !
@taylor_atx

32.
Photo by Jeremy Thomas

33.
WHAT WOULD ALLOW
YOU TO FOCUS MORE ON
THE API experience?
@taylor_atx

34.
THANK YOU! !
@taylor_atx

35.
@taylor_atx
taylor@stoplight.io

36.
APPENDIX: TOOLS THAT I MENTIONED
▸ Stoplight
▸ DapperDox
▸ ReDoc
▸ Prism
▸ Dredd
@taylor_atx