A look into designing and build RESTful APIs using OpenApi Specification and Swagger tools, with examples in Node.js.

1. Designing APIs with OpenAPI
Spec
Adam Paxton
Jazzcon.tech, New Orleans
March 23rd, 2018

2. Presentation Notes
bit.ly/openapi-notes

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

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

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

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

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

19. Demo!
Presentation Notes: bit.ly/openapi-notes