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
Average rating: ***..
(3.69, 13 ratings)

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

  • We will be using a number of different tools for this tutorial so attendees MUST set up before the session begins. Directions for doing so are under "Getting Started" here:
  • If you have any problems with the setup instructions, use the contact info in the link above.

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)


Picture of Kyle Tyacke
05/07/2017 11:37am CDT

Trying to sign up for this session and seeing a red star with the words “registration option” and no actions to take.. Does this mean the sessions full or..?

Picture of Dave Forgac
05/07/2017 11:08am CDT

The working copy of the slides are in the repo (which I see you found.) We will publish the final version of the slides online and through the OSCON site.

05/07/2017 10:16am CDT
05/07/2017 10:14am CDT

Slides present in PR#1

05/07/2017 8:57am CDT

Can you post the slides in advance?

Picture of Dave Forgac
05/02/2017 6:46pm CDT

Attending this tutorial? Try to get everything installed before the session. Repo with instructions: