SlideShare a Scribd company logo
1 of 19
Download to read offline
Designing APIs with OpenAPI
Spec
Adam Paxton
Jazzcon.tech, New Orleans
March 23rd, 2018
Presentation Notes
bit.ly/openapi-notes
Overview
• What is the OpenAPI Spec?
• Why use it?
• Swagger Tools
• Design w/ Swagger Editor
• Build w/ Codegen
• Documentation 😲 with Swagger UI
• Demo with Node.js, Angular
Hello
• Adam Paxton
• Freelance Mobile App Developer

polancomedia.com
• Location API

condesa.io



Twitter: @adampax

Github: adampax
Goals
• We all try to practice RESTful API design
• And we all try to be consistent in our design and code
• And we all try to document our API (when we get time)
Problems
• Design can be cumbersome
• Especially w/ multiple people involved
• Giant Google Doc, anyone?
• Different opinions on implementation
• Documentation is last (if at all!)
Excuses
• It’s tough, Adam. I’m busy.
• I forgot how I did it on the last endpoint.
• It was the last dev’s fault!
The OpenAPI Specification
• Standard way to describe REST APIs
• Language agnostic
• Readable for devs and non devs
• And readable by our machine overlords
Swagger OpenAPI
• Formerly known as Swagger specification, owned by SmartBear
• 2015 - Open API Initiative (OAI) was formed
• Swagger donated to OAI, renamed OpenAPI Specification (OAS)
• Linux Foundation, Google, Microsoft, IBM, etc
• Swagger now refers to a framework of OAS developer tools
The OpenAPI Document
• How you ‘design’ your API
• Contained in one or more definition files
• Uses YAML or JSON
• Can be validated, tested, ported
OpenAPI doc in a Swagger Editor
What goes in it?
• API endpoints
• Operations for each endpoint
• Input Parameters
• Responses and format
• Authentication
• API meta info
/users
GET, POST, etc
/users?active=true
200: {“name”: “adam”}
Basic Auth, OAuth2, etc
Swagger Tools
• Offers both Open Source and Commercial Tools
• Swagger Editor - design your OpenAPI spec files
• Swagger UI - documentation site generator
• Swagger CodeGen - generate server stubs and client SDKs
• Swagger Inspector - inspection and validation tool
• Swagger Node - The module we’ll be using for the demo
swagger.io
Swagger Editor
github.com/swagger-api/swagger-editor
Swagger UI
• Documentation is already written!
• Generate an API doc site from your
OpenAPI Spec
• Several open source themes available
github.com/swagger-api/swagger-ui
Swagger Codegen
• Generate server stubs, client SDKs from your OpenAPI spec
• API clients: 

ActionScript, Apex, Bash, C#, C++, Clojure, Dart Elixir, Eiffel, 

Go, Groovy, Haskell, Java, Kotlin, Lua, Node.js, Objective-C, 

Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift, Typescript
• Server stubs:

C#, C++, Erlang, Go, Haskell, Java, PHP, Python, NodeJS, Ruby, Scala
• API documentation generators: HTML, Confluence Wiki
github.com/swagger-api/swagger-codegen
Swagger Inspector
swagger.io/swagger-inspector/
OpenAPI with Node.js
• swagger-node NPM module
• CLI for creating OpenAPI based Node.js projects
• boilerplate API and spec definition
• supports Express, Restify, Hapi, Sails, Connect
• Local copy of Swagger Editor
• Uses OpenAPI Spec v2.0 (v3 released in 2017)
github.com/swagger-api/swagger-node
swagger-node
//install 

$ [sudo] npm install -g swagger
//create a project with selected framework

$ swagger project create hello-world



? Framework? (Use arrow keys)

connect

› express

hapi

restify

sails
//launch for development

swagger project start
//launch the OpenAPI doc editor

swagger project edit
Demo!
Presentation Notes: bit.ly/openapi-notes

More Related Content

What's hot

Introduction to Kong API Gateway
Introduction to Kong API GatewayIntroduction to Kong API Gateway
Introduction to Kong API GatewayYohann Ciurlik
 
OpenAPI at Scale
OpenAPI at ScaleOpenAPI at Scale
OpenAPI at ScaleNordic APIs
 
Swagger - make your API accessible
Swagger - make your API accessibleSwagger - make your API accessible
Swagger - make your API accessibleVictor Trakhtenberg
 
Building secure applications with keycloak
Building secure applications with keycloak Building secure applications with keycloak
Building secure applications with keycloak Abhishek Koserwal
 
Swagger With REST APIs.pptx.pdf
Swagger With REST APIs.pptx.pdfSwagger With REST APIs.pptx.pdf
Swagger With REST APIs.pptx.pdfKnoldus Inc.
 
GraphQL: Enabling a new generation of API developer tools
GraphQL: Enabling a new generation of API developer toolsGraphQL: Enabling a new generation of API developer tools
GraphQL: Enabling a new generation of API developer toolsSashko Stubailo
 
What is APIGEE? What are the benefits of APIGEE?
What is APIGEE? What are the benefits of APIGEE?What is APIGEE? What are the benefits of APIGEE?
What is APIGEE? What are the benefits of APIGEE?IQ Online Training
 
Api-First service design
Api-First service designApi-First service design
Api-First service designStefaan Ponnet
 
Postman Collection Format v2.0 (pre-draft)
Postman Collection Format v2.0 (pre-draft)Postman Collection Format v2.0 (pre-draft)
Postman Collection Format v2.0 (pre-draft)Postman
 
Space Camp June 2022 - API First.pdf
Space Camp June 2022 - API First.pdfSpace Camp June 2022 - API First.pdf
Space Camp June 2022 - API First.pdfPostman
 

What's hot (20)

What is Swagger?
What is Swagger?What is Swagger?
What is Swagger?
 
Introduction to Kong API Gateway
Introduction to Kong API GatewayIntroduction to Kong API Gateway
Introduction to Kong API Gateway
 
OpenAPI at Scale
OpenAPI at ScaleOpenAPI at Scale
OpenAPI at Scale
 
How Secure Are Your APIs?
How Secure Are Your APIs?How Secure Are Your APIs?
How Secure Are Your APIs?
 
Kong API
Kong APIKong API
Kong API
 
Swagger - make your API accessible
Swagger - make your API accessibleSwagger - make your API accessible
Swagger - make your API accessible
 
API Testing for everyone.pptx
API Testing for everyone.pptxAPI Testing for everyone.pptx
API Testing for everyone.pptx
 
Api types
Api typesApi types
Api types
 
Effective API Design
Effective API DesignEffective API Design
Effective API Design
 
Introduction to GraphQL
Introduction to GraphQLIntroduction to GraphQL
Introduction to GraphQL
 
Apigee Demo: API Platform Overview
Apigee Demo: API Platform OverviewApigee Demo: API Platform Overview
Apigee Demo: API Platform Overview
 
Building secure applications with keycloak
Building secure applications with keycloak Building secure applications with keycloak
Building secure applications with keycloak
 
Apigee Products Overview
Apigee Products OverviewApigee Products Overview
Apigee Products Overview
 
Swagger With REST APIs.pptx.pdf
Swagger With REST APIs.pptx.pdfSwagger With REST APIs.pptx.pdf
Swagger With REST APIs.pptx.pdf
 
GraphQL: Enabling a new generation of API developer tools
GraphQL: Enabling a new generation of API developer toolsGraphQL: Enabling a new generation of API developer tools
GraphQL: Enabling a new generation of API developer tools
 
What is APIGEE? What are the benefits of APIGEE?
What is APIGEE? What are the benefits of APIGEE?What is APIGEE? What are the benefits of APIGEE?
What is APIGEE? What are the benefits of APIGEE?
 
Api-First service design
Api-First service designApi-First service design
Api-First service design
 
Postman Collection Format v2.0 (pre-draft)
Postman Collection Format v2.0 (pre-draft)Postman Collection Format v2.0 (pre-draft)
Postman Collection Format v2.0 (pre-draft)
 
Api presentation
Api presentationApi presentation
Api presentation
 
Space Camp June 2022 - API First.pdf
Space Camp June 2022 - API First.pdfSpace Camp June 2022 - API First.pdf
Space Camp June 2022 - API First.pdf
 

Similar to Designing APIs with OpenAPI Spec

Get Your Node.js API Swaggering with OpenAPI Spec
Get Your Node.js API Swaggering with OpenAPI SpecGet Your Node.js API Swaggering with OpenAPI Spec
Get Your Node.js API Swaggering with OpenAPI SpecAdam Paxton
 
Always up to date, testable and maintainable documentation with OpenAPI
Always up to date, testable and maintainable documentation with OpenAPIAlways up to date, testable and maintainable documentation with OpenAPI
Always up to date, testable and maintainable documentation with OpenAPIGOG.com dev team
 
Developing Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & PythonDeveloping Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & PythonSmartBear
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)Tom Johnson
 
Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Tony Tam
 
Swagger for startups
Swagger for startupsSwagger for startups
Swagger for startupsTony Tam
 
Rest API with Swagger and NodeJS
Rest API with Swagger and NodeJSRest API with Swagger and NodeJS
Rest API with Swagger and NodeJSLuigi Saetta
 
Swagger: Restful documentation that won't put you to sleep
Swagger: Restful documentation that won't put you to sleepSwagger: Restful documentation that won't put you to sleep
Swagger: Restful documentation that won't put you to sleepTobias Coetzee
 
Building a REST API Microservice for the DevNet API Scavenger Hunt
Building a REST API Microservice for the DevNet API Scavenger HuntBuilding a REST API Microservice for the DevNet API Scavenger Hunt
Building a REST API Microservice for the DevNet API Scavenger HuntAshley Roach
 
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...apidays
 
Lessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SiteLessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SitePronovix
 
Open API Specifications - formerly swagger
Open API Specifications - formerly swaggerOpen API Specifications - formerly swagger
Open API Specifications - formerly swaggerPradeep Kumar
 
Delivering Developer Tools at Scale
Delivering Developer Tools at ScaleDelivering Developer Tools at Scale
Delivering Developer Tools at ScaleOracle Developers
 
A Tour of Swagger for APIs
A Tour of Swagger for APIsA Tour of Swagger for APIs
A Tour of Swagger for APIsAllen Dean
 
Design Driven API Development
Design Driven API DevelopmentDesign Driven API Development
Design Driven API DevelopmentSokichi Fujita
 
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
 
APIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadAPIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadSoftware Guru
 
OpenAPI development with Python
OpenAPI development with PythonOpenAPI development with Python
OpenAPI development with PythonTakuro Wada
 

Similar to Designing APIs with OpenAPI Spec (20)

Get Your Node.js API Swaggering with OpenAPI Spec
Get Your Node.js API Swaggering with OpenAPI SpecGet Your Node.js API Swaggering with OpenAPI Spec
Get Your Node.js API Swaggering with OpenAPI Spec
 
Always up to date, testable and maintainable documentation with OpenAPI
Always up to date, testable and maintainable documentation with OpenAPIAlways up to date, testable and maintainable documentation with OpenAPI
Always up to date, testable and maintainable documentation with OpenAPI
 
Developing Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & PythonDeveloping Brilliant and Powerful APIs in Ruby & Python
Developing Brilliant and Powerful APIs in Ruby & Python
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)
 
Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)
 
Swagger for startups
Swagger for startupsSwagger for startups
Swagger for startups
 
Rest API with Swagger and NodeJS
Rest API with Swagger and NodeJSRest API with Swagger and NodeJS
Rest API with Swagger and NodeJS
 
Swagger: Restful documentation that won't put you to sleep
Swagger: Restful documentation that won't put you to sleepSwagger: Restful documentation that won't put you to sleep
Swagger: Restful documentation that won't put you to sleep
 
Building a REST API Microservice for the DevNet API Scavenger Hunt
Building a REST API Microservice for the DevNet API Scavenger HuntBuilding a REST API Microservice for the DevNet API Scavenger Hunt
Building a REST API Microservice for the DevNet API Scavenger Hunt
 
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by  Ilona Ko...
APIdays Paris 2019 - Lessons Learned from Revamping our Doc Site by Ilona Ko...
 
Lessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc SiteLessons Learned from Revamping Our Doc Site
Lessons Learned from Revamping Our Doc Site
 
Open API Specifications - formerly swagger
Open API Specifications - formerly swaggerOpen API Specifications - formerly swagger
Open API Specifications - formerly swagger
 
Delivering Developer Tools at Scale
Delivering Developer Tools at ScaleDelivering Developer Tools at Scale
Delivering Developer Tools at Scale
 
A Tour of Swagger for APIs
A Tour of Swagger for APIsA Tour of Swagger for APIs
A Tour of Swagger for APIs
 
Design Driven API Development
Design Driven API DevelopmentDesign Driven API Development
Design Driven API Development
 
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
 
APIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadAPIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidad
 
SGCE 2015 REST APIs
SGCE 2015 REST APIsSGCE 2015 REST APIs
SGCE 2015 REST APIs
 
API Conference 2021
API Conference 2021API Conference 2021
API Conference 2021
 
OpenAPI development with Python
OpenAPI development with PythonOpenAPI development with Python
OpenAPI development with Python
 

More from Adam Paxton

Geolocation for Mobile Apps - Connect.tech Atlanta, 2017
Geolocation for Mobile Apps - Connect.tech Atlanta, 2017Geolocation for Mobile Apps - Connect.tech Atlanta, 2017
Geolocation for Mobile Apps - Connect.tech Atlanta, 2017Adam Paxton
 
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...Adam Paxton
 
Continuous Cross Platform Mobile App Development using Jenkins Build Server
Continuous Cross Platform Mobile App Development using Jenkins Build ServerContinuous Cross Platform Mobile App Development using Jenkins Build Server
Continuous Cross Platform Mobile App Development using Jenkins Build ServerAdam Paxton
 
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015Adam Paxton
 
Introduction to Appcelerator Titanium
Introduction to Appcelerator TitaniumIntroduction to Appcelerator Titanium
Introduction to Appcelerator TitaniumAdam Paxton
 
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...Adam Paxton
 

More from Adam Paxton (6)

Geolocation for Mobile Apps - Connect.tech Atlanta, 2017
Geolocation for Mobile Apps - Connect.tech Atlanta, 2017Geolocation for Mobile Apps - Connect.tech Atlanta, 2017
Geolocation for Mobile Apps - Connect.tech Atlanta, 2017
 
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...
The Big Easy: Native Mobile App Development with Appcelerator Titanium and Ja...
 
Continuous Cross Platform Mobile App Development using Jenkins Build Server
Continuous Cross Platform Mobile App Development using Jenkins Build ServerContinuous Cross Platform Mobile App Development using Jenkins Build Server
Continuous Cross Platform Mobile App Development using Jenkins Build Server
 
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015
Intro to Appcelerator Titanium - Code for Fort Lauderdale 2015
 
Introduction to Appcelerator Titanium
Introduction to Appcelerator TitaniumIntroduction to Appcelerator Titanium
Introduction to Appcelerator Titanium
 
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...
Build Custom Maps with Appcelerator Titanium, Mapbox and OpenStreetMap - tiCo...
 

Recently uploaded

Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...
Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...
Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...Milind Agarwal
 
Effort Estimation Techniques used in Software Projects
Effort Estimation Techniques used in Software ProjectsEffort Estimation Techniques used in Software Projects
Effort Estimation Techniques used in Software ProjectsDEEPRAJ PATHAK
 
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptx
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptxSPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptx
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptxVersion 1 Analytics
 
Zer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfZer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfmaor17
 
Santander Stream Processing with Apache Flink
Santander Stream Processing with Apache FlinkSantander Stream Processing with Apache Flink
Santander Stream Processing with Apache Flinkconfluent
 
Mastering Project Planning with Microsoft Project 2016.pptx
Mastering Project Planning with Microsoft Project 2016.pptxMastering Project Planning with Microsoft Project 2016.pptx
Mastering Project Planning with Microsoft Project 2016.pptxAS Design & AST.
 
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...Bert Jan Schrijver
 
oracle 23c new features for developer and dba
oracle 23c new features for developer and dbaoracle 23c new features for developer and dba
oracle 23c new features for developer and dbaRemote DBA Services
 
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfPros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfkalichargn70th171
 
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jGraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jNeo4j
 
Keeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldKeeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldRoberto Pérez Alcolea
 
eSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolseSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolsosttopstonverter
 
Effectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorEffectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorTier1 app
 
Business Analyzopedia - Your Pocket Gita for Business Analysis
Business Analyzopedia - Your Pocket Gita for Business AnalysisBusiness Analyzopedia - Your Pocket Gita for Business Analysis
Business Analyzopedia - Your Pocket Gita for Business AnalysisDEEPRAJ PATHAK
 
Tech Tuesday Slides - Getting Started with the Portfolio Module.
Tech Tuesday Slides - Getting Started with the Portfolio Module.Tech Tuesday Slides - Getting Started with the Portfolio Module.
Tech Tuesday Slides - Getting Started with the Portfolio Module.OnePlan Solutions
 
Reliable from-source builds (Qshare 28 Nov 2023).pdf
Reliable from-source builds (Qshare 28 Nov 2023).pdfReliable from-source builds (Qshare 28 Nov 2023).pdf
Reliable from-source builds (Qshare 28 Nov 2023).pdfRalf Gommers
 
Chapter -5 Agile Testing types and its examples.pptx
Chapter -5 Agile Testing types and its examples.pptxChapter -5 Agile Testing types and its examples.pptx
Chapter -5 Agile Testing types and its examples.pptxManishaPatil932723
 
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBU
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBUETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBU
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBUsamruddhijedgule2004
 
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...Bert Jan Schrijver
 
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...OnePlan Solutions
 

Recently uploaded (20)

Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...
Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...
Leveraging the Expertise of a Social Media Fraud Analyst to Safeguard Brand R...
 
Effort Estimation Techniques used in Software Projects
Effort Estimation Techniques used in Software ProjectsEffort Estimation Techniques used in Software Projects
Effort Estimation Techniques used in Software Projects
 
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptx
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptxSPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptx
SPSS Statistics - Encrypting a Syntax File in IBM SPSS Statistics.pptx
 
Zer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfZer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdf
 
Santander Stream Processing with Apache Flink
Santander Stream Processing with Apache FlinkSantander Stream Processing with Apache Flink
Santander Stream Processing with Apache Flink
 
Mastering Project Planning with Microsoft Project 2016.pptx
Mastering Project Planning with Microsoft Project 2016.pptxMastering Project Planning with Microsoft Project 2016.pptx
Mastering Project Planning with Microsoft Project 2016.pptx
 
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
 
oracle 23c new features for developer and dba
oracle 23c new features for developer and dbaoracle 23c new features for developer and dba
oracle 23c new features for developer and dba
 
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfPros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
 
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jGraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
 
Keeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldKeeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository world
 
eSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolseSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration tools
 
Effectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorEffectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryError
 
Business Analyzopedia - Your Pocket Gita for Business Analysis
Business Analyzopedia - Your Pocket Gita for Business AnalysisBusiness Analyzopedia - Your Pocket Gita for Business Analysis
Business Analyzopedia - Your Pocket Gita for Business Analysis
 
Tech Tuesday Slides - Getting Started with the Portfolio Module.
Tech Tuesday Slides - Getting Started with the Portfolio Module.Tech Tuesday Slides - Getting Started with the Portfolio Module.
Tech Tuesday Slides - Getting Started with the Portfolio Module.
 
Reliable from-source builds (Qshare 28 Nov 2023).pdf
Reliable from-source builds (Qshare 28 Nov 2023).pdfReliable from-source builds (Qshare 28 Nov 2023).pdf
Reliable from-source builds (Qshare 28 Nov 2023).pdf
 
Chapter -5 Agile Testing types and its examples.pptx
Chapter -5 Agile Testing types and its examples.pptxChapter -5 Agile Testing types and its examples.pptx
Chapter -5 Agile Testing types and its examples.pptx
 
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBU
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBUETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBU
ETE PPT.pdf LMMKLMKLMLKMLLMJKBHJBHBNUIHBU
 
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...
AmsterdamJUG April 2024 - Going serverless with Quarkus GraalVM native images...
 
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
 

Designing APIs with OpenAPI Spec

  • 1. Designing APIs with OpenAPI Spec Adam Paxton Jazzcon.tech, New Orleans March 23rd, 2018
  • 3. Overview • What is the OpenAPI Spec? • Why use it? • Swagger Tools • Design w/ Swagger Editor • Build w/ Codegen • Documentation 😲 with Swagger UI • Demo with Node.js, Angular
  • 4. Hello • Adam Paxton • Freelance Mobile App Developer
 polancomedia.com • Location API
 condesa.io
 
 Twitter: @adampax
 Github: adampax
  • 5. Goals • We all try to practice RESTful API design • And we all try to be consistent in our design and code • And we all try to document our API (when we get time)
  • 6. Problems • Design can be cumbersome • Especially w/ multiple people involved • Giant Google Doc, anyone? • Different opinions on implementation • Documentation is last (if at all!)
  • 7. Excuses • It’s tough, Adam. I’m busy. • I forgot how I did it on the last endpoint. • It was the last dev’s fault!
  • 8. The OpenAPI Specification • Standard way to describe REST APIs • Language agnostic • Readable for devs and non devs • And readable by our machine overlords
  • 9. Swagger OpenAPI • Formerly known as Swagger specification, owned by SmartBear • 2015 - Open API Initiative (OAI) was formed • Swagger donated to OAI, renamed OpenAPI Specification (OAS) • Linux Foundation, Google, Microsoft, IBM, etc • Swagger now refers to a framework of OAS developer tools
  • 10. The OpenAPI Document • How you ‘design’ your API • Contained in one or more definition files • Uses YAML or JSON • Can be validated, tested, ported OpenAPI doc in a Swagger Editor
  • 11. What goes in it? • API endpoints • Operations for each endpoint • Input Parameters • Responses and format • Authentication • API meta info /users GET, POST, etc /users?active=true 200: {“name”: “adam”} Basic Auth, OAuth2, etc
  • 12. Swagger Tools • Offers both Open Source and Commercial Tools • Swagger Editor - design your OpenAPI spec files • Swagger UI - documentation site generator • Swagger CodeGen - generate server stubs and client SDKs • Swagger Inspector - inspection and validation tool • Swagger Node - The module we’ll be using for the demo swagger.io
  • 14. Swagger UI • Documentation is already written! • Generate an API doc site from your OpenAPI Spec • Several open source themes available github.com/swagger-api/swagger-ui
  • 15. Swagger Codegen • Generate server stubs, client SDKs from your OpenAPI spec • API clients: 
 ActionScript, Apex, Bash, C#, C++, Clojure, Dart Elixir, Eiffel, 
 Go, Groovy, Haskell, Java, Kotlin, Lua, Node.js, Objective-C, 
 Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift, Typescript • Server stubs:
 C#, C++, Erlang, Go, Haskell, Java, PHP, Python, NodeJS, Ruby, Scala • API documentation generators: HTML, Confluence Wiki github.com/swagger-api/swagger-codegen
  • 17. OpenAPI with Node.js • swagger-node NPM module • CLI for creating OpenAPI based Node.js projects • boilerplate API and spec definition • supports Express, Restify, Hapi, Sails, Connect • Local copy of Swagger Editor • Uses OpenAPI Spec v2.0 (v3 released in 2017) github.com/swagger-api/swagger-node
  • 18. swagger-node //install 
 $ [sudo] npm install -g swagger //create a project with selected framework
 $ swagger project create hello-world
 
 ? Framework? (Use arrow keys)
 connect
 › express
 hapi
 restify
 sails //launch for development
 swagger project start //launch the OpenAPI doc editor
 swagger project edit