Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Designing APIs with OpenAPI Spec


Published on

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

Published in: Software
  • Login to see the comments

Designing APIs with OpenAPI Spec

  1. 1. Designing APIs with OpenAPI Spec Adam Paxton, New Orleans March 23rd, 2018
  2. 2. Presentation Notes
  3. 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. 4. Hello • Adam Paxton • Freelance Mobile App Developer • Location API
 Twitter: @adampax
 Github: adampax
  5. 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. 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. 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. 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. 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. 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. 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. 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
  13. 13. Swagger Editor
  14. 14. Swagger UI • Documentation is already written! • Generate an API doc site from your OpenAPI Spec • Several open source themes available
  15. 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
  16. 16. Swagger Inspector
  17. 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)
  18. 18. swagger-node //install 
 $ [sudo] npm install -g swagger //create a project with selected framework
 $ swagger project create hello-world
 ? Framework? (Use arrow keys)
 › express
 sails //launch for development
 swagger project start //launch the OpenAPI doc editor
 swagger project edit
  19. 19. Demo! Presentation Notes: