It’s specifying the version of the Open API specification we’re using (currently the latest 2.0) as well as some other basic information about our API like a description and title. The above block of code is laying down some baseline information about our API. swagger : ' 2.0' info : description : ' Dwarf Tracker endpoints' version : ' 0.0.1' title : ' Dwarf Tracker Service API' host : ' localhost:3000' schemes : - ' http' produces : - ' application/json' Then open that file in your favorite text editor and paste in the following code. Once you’ve created a new folder / directory to store your project create a swagger.yml file. So change directory to somewhere you’d like to create a new project. To start off, we’ll just need to create a new swagger.yml specification file.

Our API will handle simple Create and Read operations for keeping track of Dwarf migrants we meet in Dwarf Fortress. To demonstrate how we can quickly write both the server-side and client-side code for an app we’re going to build an app for keeping track of Dwarfs we meet while playing Dwarf Fortress.įirst we’ll need to create a swagger specification that will define the entire backend API for our app. You’ll see how this works in a minute when we start writing code. In other words once you create a swagger spec document (in either json or yml) that defines the expected behavior of an API you can just generate the code to interact with that endpoint because the expectations on both sides of the agreement have already been defined. One of Swagger’s lesser known features is the capability to generate server AND client code (yes even Swift!).Īll this is made possible with Swagger’s Open API Specification which defines a standard by which a REST API’s functionality can be defined. It also allows you to test calls directly from your browser. Swagger’s documentation is easy to read and understand. Swagger’s UI tool makes it easy to learn about the features of a backend service you’d like to interact with without needing to dig through interminable and abstruse documentation. (Here’s a quick look at what Swagger UI Looks like with a defined API) If you’ve ever worked on an app with it’s own backend service before then you may have used swagger’s easy to use (and generate) Swagger UI documentation. This tutorial will introduce you to how Swagger Codegen can save you tons of time on both the front and backend when building an integrated app. Huge portions of the code on both the front and backend will be automatically generated. In this tutorial I’ll walk you through building a working Swift 3 App and a working NodeJS Service.

Swagger editor for node.js download