SlideShare a Scribd company logo
1 of 36
GOING TO INFINITY AND Beyond
Documentation WITH OPENAPI
@TAYLOR_ATX
HI! ! I'M THE LEAD COMMUNITY
ENGINEER AT Stoplight
FIND ME ON TWITTER @TAYLOR_ATX OR
TAYLOR@STOPLIGHT.IO
SINGLE SOURCE OF
TRUTH
@taylor_atx
SELF-DOCUMENTING APIS DO not EXIST
@taylor_atx
WHAT IS OpenAPI
Specification?(FKA SWAGGER)
@taylor_atx
STANDARD, structured approach FOR
DESCRIBING APIS THAT IS BOTH
human AND machine READABLE
@taylor_atx
"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
HIDDEN OPENAPI
BENEFITS ✨
@taylor_atx
IT IS not JUST FOR API
REFERENCES !
@taylor_atx
IT IS not JUST FOR API REFERENCES
▸ Development contract
▸ Prototyping and mocking
▸ Client SDKs and libraries
▸ Testing
▸ Server stubs
@taylor_atx
YOU GET TO FOCUS ON
THE good stuff !
@taylor_atx
TOOL FOR
Collaboration !
@taylor_atx
TOOL FOR Collaboration
▸ Simplifies describing an API
▸ Standardizes terminology
▸ "API Fastness"
@taylor_atx
ENHANCES Developer
Experience !
@taylor_atx
ENHANCES Developer Experience
1. Design-First
2. Mocking and Feedback
3. Testing
@taylor_atx
1. DESIGN-FIRST
@taylor_atx
DESIGN-FIRST
▸ Consistency for users
▸ Important for critical APIs
▸ Code-first can be expensive
▸ Gain the benefits of using OpenAPI
@taylor_atx
2. MOCKING AND
FEEDBACK
@taylor_atx
WHY Should YOU CARE
ABOUT MOCKING?
@taylor_atx
IF YOU WRITE DOCS, TUTORIALS, AND CONTENT, YOU CAN...
▸ Start writing sooner
▸ Give feedback
▸ Have more interactive docs
@taylor_atx
IF YOU MAINTAIN CLIENT LIBRARIES OR SDKS, YOU CAN...
▸ More options
▸ Create libraries and SDKs faster
▸ Have libraries ready at release
@taylor_atx
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
"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
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
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
3. TESTING
@taylor_atx
TESTING
▸ Gain the benefits of it being machine readable
▸ All kinds of validation testing
▸ Prioritize the experience
@taylor_atx
CONTRACT TESTING
@taylor_atx
CONTRACT TESTING
@taylor_atx
LESS SUPPORT OVERHEAD
!
LESS CONFUSION AND HEADACHE
!
HAPPIER USERS (INCLUDING YOU!)
@taylor_atx
THE REALITY !
@taylor_atx
Photo by Jeremy Thomas
WHAT WOULD ALLOW
YOU TO FOCUS MORE ON
THE API experience?
@taylor_atx
THANK YOU! !
@taylor_atx
@taylor_atx
taylor@stoplight.io
APPENDIX: TOOLS THAT I MENTIONED
▸ Stoplight
▸ DapperDox
▸ ReDoc
▸ Prism
▸ Dredd
@taylor_atx

More Related Content

What's hot

I Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
I Love APIs 2015 API Lab Design-first API Development Using Node and SwaggerI Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
I Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
Apigee | Google Cloud
 

What's hot (20)

Going Reactive with Spring 5 & Project Reactor
Going Reactive with Spring 5 & Project ReactorGoing Reactive with Spring 5 & Project Reactor
Going Reactive with Spring 5 & Project Reactor
 
Search and Discovery With Public and Private API Networks
Search and Discovery With Public and Private API NetworksSearch and Discovery With Public and Private API Networks
Search and Discovery With Public and Private API Networks
 
State of the API: Insights Into the Future of APIs
State of the API: Insights Into the Future of APIsState of the API: Insights Into the Future of APIs
State of the API: Insights Into the Future of APIs
 
Ultimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsUltimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation Solutions
 
Building Self Documenting REST APIs
Building Self Documenting REST APIsBuilding Self Documenting REST APIs
Building Self Documenting REST APIs
 
Using APIs to Program Disparate IoT Devices
Using APIs to Program Disparate IoT DevicesUsing APIs to Program Disparate IoT Devices
Using APIs to Program Disparate IoT Devices
 
Past, Present, Future of APIS
Past, Present, Future of APISPast, Present, Future of APIS
Past, Present, Future of APIS
 
Clouds & Containers: Hit the High Points and Give it to Me Straight, What's t...
Clouds & Containers: Hit the High Points and Give it to Me Straight, What's t...Clouds & Containers: Hit the High Points and Give it to Me Straight, What's t...
Clouds & Containers: Hit the High Points and Give it to Me Straight, What's t...
 
Postman covid-webinar
Postman covid-webinarPostman covid-webinar
Postman covid-webinar
 
Inside mind of a successful platform architect / Gartner APPS 2016
Inside mind of a successful platform architect / Gartner APPS 2016 Inside mind of a successful platform architect / Gartner APPS 2016
Inside mind of a successful platform architect / Gartner APPS 2016
 
Scaling Your Team With GraphQL: Why Relationships Matter
Scaling Your Team With GraphQL: Why Relationships MatterScaling Your Team With GraphQL: Why Relationships Matter
Scaling Your Team With GraphQL: Why Relationships Matter
 
Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014
Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014
Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014
 
I Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
I Love APIs 2015 API Lab Design-first API Development Using Node and SwaggerI Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
I Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
 
reCAPTCHAとSkyWayのAPI認証で手軽に利用できて不正利用に強いアプリを作ろう
reCAPTCHAとSkyWayのAPI認証で手軽に利用できて不正利用に強いアプリを作ろうreCAPTCHAとSkyWayのAPI認証で手軽に利用できて不正利用に強いアプリを作ろう
reCAPTCHAとSkyWayのAPI認証で手軽に利用できて不正利用に強いアプリを作ろう
 
Postman Webinar: "API Governance with Postman"
Postman Webinar: "API Governance with Postman"Postman Webinar: "API Governance with Postman"
Postman Webinar: "API Governance with Postman"
 
Google APIs for NSBM Students
Google APIs for NSBM StudentsGoogle APIs for NSBM Students
Google APIs for NSBM Students
 
JNation: REST APIs to GraphQL with Express and Apollo
JNation: REST APIs to GraphQL with Express and ApolloJNation: REST APIs to GraphQL with Express and Apollo
JNation: REST APIs to GraphQL with Express and Apollo
 
Enterprise E-commerce Webinar Series, Episode 2: Deploying and Monitoring You...
Enterprise E-commerce Webinar Series, Episode 2: Deploying and Monitoring You...Enterprise E-commerce Webinar Series, Episode 2: Deploying and Monitoring You...
Enterprise E-commerce Webinar Series, Episode 2: Deploying and Monitoring You...
 
OpenAPI at Scale
OpenAPI at ScaleOpenAPI at Scale
OpenAPI at Scale
 
JAX London 2021: Jumpstart Your Cloud Native Development: An Overview of Prac...
JAX London 2021: Jumpstart Your Cloud Native Development: An Overview of Prac...JAX London 2021: Jumpstart Your Cloud Native Development: An Overview of Prac...
JAX London 2021: Jumpstart Your Cloud Native Development: An Overview of Prac...
 

Similar to Going to Infinity and Beyond Documentation with OpenAPI

Creating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKsCreating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKs
Taylor Barnett
 
In graph we trust: Microservices, GraphQL and security challenges
In graph we trust: Microservices, GraphQL and security challengesIn graph we trust: Microservices, GraphQL and security challenges
In graph we trust: Microservices, GraphQL and security challenges
Mohammed A. Imran
 
5 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 20135 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 2013
Daniel Feist
 
Building Open Source Communities for AWS Serverless Developer Tools
Building Open Source Communities for AWS Serverless Developer ToolsBuilding Open Source Communities for AWS Serverless Developer Tools
Building Open Source Communities for AWS Serverless Developer Tools
Amazon Web Services
 
API Athens Meetup - API standards 25-6-2014
API Athens Meetup - API standards   25-6-2014API Athens Meetup - API standards   25-6-2014
API Athens Meetup - API standards 25-6-2014
Michael Petychakis
 
apache solr web development.pdf
apache solr web development.pdfapache solr web development.pdf
apache solr web development.pdf
Tasnim Jahan
 

Similar to Going to Infinity and Beyond Documentation with OpenAPI (20)

Creating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKsCreating a Great Developer Experience Through SDKs
Creating a Great Developer Experience Through SDKs
 
Testing libraries for fun & profit. Beware: Increased productivity ahead
Testing libraries for fun & profit. Beware: Increased productivity aheadTesting libraries for fun & profit. Beware: Increased productivity ahead
Testing libraries for fun & profit. Beware: Increased productivity ahead
 
DevSecCon Singapore 2018 - in graph we trust By Imran Mohammed
DevSecCon Singapore 2018 - in graph we trust By Imran MohammedDevSecCon Singapore 2018 - in graph we trust By Imran Mohammed
DevSecCon Singapore 2018 - in graph we trust By Imran Mohammed
 
In graph we trust: Microservices, GraphQL and security challenges
In graph we trust: Microservices, GraphQL and security challengesIn graph we trust: Microservices, GraphQL and security challenges
In graph we trust: Microservices, GraphQL and security challenges
 
Mulesoft Raml APIs
Mulesoft Raml APIsMulesoft Raml APIs
Mulesoft Raml APIs
 
5 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 20135 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 2013
 
Building Open Source Communities for AWS Serverless Developer Tools
Building Open Source Communities for AWS Serverless Developer ToolsBuilding Open Source Communities for AWS Serverless Developer Tools
Building Open Source Communities for AWS Serverless Developer Tools
 
Jarkko Moilanen, APInf, “Get Control of Your IoT Cruisers” - Mindtrek 2017
Jarkko Moilanen, APInf, “Get Control of Your IoT Cruisers” - Mindtrek 2017Jarkko Moilanen, APInf, “Get Control of Your IoT Cruisers” - Mindtrek 2017
Jarkko Moilanen, APInf, “Get Control of Your IoT Cruisers” - Mindtrek 2017
 
How to contribute to Serverless Apache OpenWhisk OpenSource101 NCSU
How to contribute to Serverless Apache OpenWhisk OpenSource101 NCSUHow to contribute to Serverless Apache OpenWhisk OpenSource101 NCSU
How to contribute to Serverless Apache OpenWhisk OpenSource101 NCSU
 
Speaking APIsh makes your business more agile
Speaking APIsh makes your business more agileSpeaking APIsh makes your business more agile
Speaking APIsh makes your business more agile
 
Literature Text Translation & Audio Synthesis using Microsoft Azure Cognitive...
Literature Text Translation & Audio Synthesis using Microsoft Azure Cognitive...Literature Text Translation & Audio Synthesis using Microsoft Azure Cognitive...
Literature Text Translation & Audio Synthesis using Microsoft Azure Cognitive...
 
Backstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptxBackstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptx
 
API Athens Meetup - API standards 25-6-2014
API Athens Meetup - API standards 25-6-2014API Athens Meetup - API standards 25-6-2014
API Athens Meetup - API standards 25-6-2014
 
API Athens Meetup - API standards 25-6-2014
API Athens Meetup - API standards   25-6-2014API Athens Meetup - API standards   25-6-2014
API Athens Meetup - API standards 25-6-2014
 
Introduction to the Art of API Practice
Introduction to the Art of API PracticeIntroduction to the Art of API Practice
Introduction to the Art of API Practice
 
A Snapshot of API Design Trends In 2019
A Snapshot of API Design Trends In 2019A Snapshot of API Design Trends In 2019
A Snapshot of API Design Trends In 2019
 
RAML - APIs By Design
RAML - APIs By DesignRAML - APIs By Design
RAML - APIs By Design
 
Build Better. Build Faster. - How to Transform DevOps for Quality at Speed
Build Better. Build Faster.  - How to Transform DevOps for Quality at SpeedBuild Better. Build Faster.  - How to Transform DevOps for Quality at Speed
Build Better. Build Faster. - How to Transform DevOps for Quality at Speed
 
OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead
OpenAPI v.Next - Events, Alternative Schemas & the Road AheadOpenAPI v.Next - Events, Alternative Schemas & the Road Ahead
OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead
 
apache solr web development.pdf
apache solr web development.pdfapache solr web development.pdf
apache solr web development.pdf
 

Recently uploaded

TECUNIQUE: Success Stories: IT Service provider
TECUNIQUE: Success Stories: IT Service providerTECUNIQUE: Success Stories: IT Service provider
TECUNIQUE: Success Stories: IT Service provider
mohitmore19
 
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
Health
 
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online ☂️
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online  ☂️CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online  ☂️
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online ☂️
anilsa9823
 
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICECHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
9953056974 Low Rate Call Girls In Saket, Delhi NCR
 

Recently uploaded (20)

HR Software Buyers Guide in 2024 - HRSoftware.com
HR Software Buyers Guide in 2024 - HRSoftware.comHR Software Buyers Guide in 2024 - HRSoftware.com
HR Software Buyers Guide in 2024 - HRSoftware.com
 
Reassessing the Bedrock of Clinical Function Models: An Examination of Large ...
Reassessing the Bedrock of Clinical Function Models: An Examination of Large ...Reassessing the Bedrock of Clinical Function Models: An Examination of Large ...
Reassessing the Bedrock of Clinical Function Models: An Examination of Large ...
 
How To Use Server-Side Rendering with Nuxt.js
How To Use Server-Side Rendering with Nuxt.jsHow To Use Server-Side Rendering with Nuxt.js
How To Use Server-Side Rendering with Nuxt.js
 
TECUNIQUE: Success Stories: IT Service provider
TECUNIQUE: Success Stories: IT Service providerTECUNIQUE: Success Stories: IT Service provider
TECUNIQUE: Success Stories: IT Service provider
 
Shapes for Sharing between Graph Data Spaces - and Epistemic Querying of RDF-...
Shapes for Sharing between Graph Data Spaces - and Epistemic Querying of RDF-...Shapes for Sharing between Graph Data Spaces - and Epistemic Querying of RDF-...
Shapes for Sharing between Graph Data Spaces - and Epistemic Querying of RDF-...
 
Unveiling the Tech Salsa of LAMs with Janus in Real-Time Applications
Unveiling the Tech Salsa of LAMs with Janus in Real-Time ApplicationsUnveiling the Tech Salsa of LAMs with Janus in Real-Time Applications
Unveiling the Tech Salsa of LAMs with Janus in Real-Time Applications
 
Right Money Management App For Your Financial Goals
Right Money Management App For Your Financial GoalsRight Money Management App For Your Financial Goals
Right Money Management App For Your Financial Goals
 
The Real-World Challenges of Medical Device Cybersecurity- Mitigating Vulnera...
The Real-World Challenges of Medical Device Cybersecurity- Mitigating Vulnera...The Real-World Challenges of Medical Device Cybersecurity- Mitigating Vulnera...
The Real-World Challenges of Medical Device Cybersecurity- Mitigating Vulnera...
 
Steps To Getting Up And Running Quickly With MyTimeClock Employee Scheduling ...
Steps To Getting Up And Running Quickly With MyTimeClock Employee Scheduling ...Steps To Getting Up And Running Quickly With MyTimeClock Employee Scheduling ...
Steps To Getting Up And Running Quickly With MyTimeClock Employee Scheduling ...
 
Short Story: Unveiling the Reasoning Abilities of Large Language Models by Ke...
Short Story: Unveiling the Reasoning Abilities of Large Language Models by Ke...Short Story: Unveiling the Reasoning Abilities of Large Language Models by Ke...
Short Story: Unveiling the Reasoning Abilities of Large Language Models by Ke...
 
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
+971565801893>>SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHAB...
 
Optimizing AI for immediate response in Smart CCTV
Optimizing AI for immediate response in Smart CCTVOptimizing AI for immediate response in Smart CCTV
Optimizing AI for immediate response in Smart CCTV
 
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online ☂️
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online  ☂️CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online  ☂️
CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online ☂️
 
The Ultimate Test Automation Guide_ Best Practices and Tips.pdf
The Ultimate Test Automation Guide_ Best Practices and Tips.pdfThe Ultimate Test Automation Guide_ Best Practices and Tips.pdf
The Ultimate Test Automation Guide_ Best Practices and Tips.pdf
 
A Secure and Reliable Document Management System is Essential.docx
A Secure and Reliable Document Management System is Essential.docxA Secure and Reliable Document Management System is Essential.docx
A Secure and Reliable Document Management System is Essential.docx
 
How To Troubleshoot Collaboration Apps for the Modern Connected Worker
How To Troubleshoot Collaboration Apps for the Modern Connected WorkerHow To Troubleshoot Collaboration Apps for the Modern Connected Worker
How To Troubleshoot Collaboration Apps for the Modern Connected Worker
 
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICECHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
CHEAP Call Girls in Pushp Vihar (-DELHI )🔝 9953056974🔝(=)/CALL GIRLS SERVICE
 
Software Quality Assurance Interview Questions
Software Quality Assurance Interview QuestionsSoftware Quality Assurance Interview Questions
Software Quality Assurance Interview Questions
 
call girls in Vaishali (Ghaziabad) 🔝 >༒8448380779 🔝 genuine Escort Service 🔝✔️✔️
call girls in Vaishali (Ghaziabad) 🔝 >༒8448380779 🔝 genuine Escort Service 🔝✔️✔️call girls in Vaishali (Ghaziabad) 🔝 >༒8448380779 🔝 genuine Escort Service 🔝✔️✔️
call girls in Vaishali (Ghaziabad) 🔝 >༒8448380779 🔝 genuine Escort Service 🔝✔️✔️
 
W01_panagenda_Navigating-the-Future-with-The-Hitchhikers-Guide-to-Notes-and-D...
W01_panagenda_Navigating-the-Future-with-The-Hitchhikers-Guide-to-Notes-and-D...W01_panagenda_Navigating-the-Future-with-The-Hitchhikers-Guide-to-Notes-and-D...
W01_panagenda_Navigating-the-Future-with-The-Hitchhikers-Guide-to-Notes-and-D...
 

Going to Infinity and Beyond Documentation with OpenAPI