An overview of OpenAPI Spec, fka Swagger, as well as an example of how to use it when building a Node.js REST API. Presented at Connect.tech Atlanta, September 21, 2017.

1. Get Your Node.js API
Swaggering with OpenAPI Spec
Adam Paxton
Connect.tech Atlanta
September 21st, 2017

2. Presentation Notes
bit.ly/swaggernodejs

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

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. 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

12. Swagger Editor
github.com/swagger-api/swagger-editor

13. 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

14. 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

15. Swagger Inspector
swagger.io/swagger-inspector/

16. 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

17. 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

18. Demo!
Presentation Notes: bit.ly/swaggernodejs