Making Open Work
May 8–9, 2017: Training & Tutorials
May 10–11, 2017: Conference
Austin, TX

Contract-first API development using the OpenAPI Specification (formerly Swagger)

Dave Forgac (American Greetings), Ian Zelikman (IBM Watson Health)
9:00am12:30pm Tuesday, May 9, 2017
Adopt This Now
Location: Meeting Room 9
Level: Intermediate

Who is this presentation for?

  • Developers and engineers who produce APIs

Prerequisite knowledge

  • Familiarity with HTTP APIs and REST concepts
  • Experience with programming web services and applications (in any language)

Materials or downloads needed in advance

  • A laptop with Node.js installed and a clone of the course Git repo (link provided prior to tutorial)

What you'll learn

  • Learn how to incorporate a contract-first process into your API development workflow
  • Discover an example specification that can be used as reference for your own API design
  • Build working code for a basic API that can be used as a basis for your own development


Some developers implement APIs, thinking about things like specifications and documentation only after they’re released. Dave Forgac and Ian Zelikman demonstrate how to use a contract-first approach to API development using the OpenAPI Specification (formerly called Swagger) and other open source tools. Dave and Ian walk you through defining a simple API specification, using it to generate documentation, a mock server, and stub code, and implementing a working API based on the specification.

Topics include:

  • The contract-first approach
  • Building and validating a simple OpenAPI Specification
  • Generating reference documentation and incorporating it with other docs
  • Running a mock server so clients can test using the API
  • Generating stub code based on the specification
  • Implementing a basic working API
  • Iteratively adding features and making changes
  • Generating specifications for existing APIs
Photo of Dave Forgac

Dave Forgac

American Greetings

Dave Forgac is a senior software engineer at American Greetings in Cleveland, where he is responsible for API development, application deployment, and developer happiness engineering. Dave has been a FOSS enthusiast ever since installing Linux for the first time in the late ’90’s. He loves building communities and is an organizer of PyOhio, ClePy, and the Cleveland API Meetup.

Photo of Ian Zelikman

Ian Zelikman

IBM Watson Health

Ian Zelikman is a software engineer at IBM Watson Health, where he works with big data and healthcare. Ian has worked with web technologies for over 10 years, ever since his first job developing applications for weather forecasting and analysis. Ian has been a Pythonista for over four years experience developing scalable and reliable backend systems and designing and integrating with web APIs.

Leave a Comment or Question

Help us make this conference the best it can be for you. Have questions you'd like this speaker to address? Suggestions for issues that deserve extra attention? Feedback that you'd like to share with the speaker and other attendees?

Join the conversation here (requires login)