The OpenAPI Spec and Kitura: Getting Started

Time and experience have refined the principles of using REST, and most everyone who writes a REST API these days adheres to these common standards.

However, this standard leaves considerable room for variation. Developers tend to write RESTful APIs in their own style, and understanding the specifics of how a given back-end is structured can be difficult. Further, developers often take widely ranging approaches to documenting APIs, further adding to the difficulties awaiting you when encountering a new API.

In 2011, Tony Tam of the dictionary website wordnik.com encountered these very issues. He lamented the pain of needing to rewrite client-side SDKs every time developers updated a corresponding REST API. Necessity is the mother of invention, as the saying goes, and out of this pain the Swagger API project was born.

In this tutorial, you’ll get a quick overview of the history of this specification, and you’ll learn how you can use it to represent your Kitura API throughout the development of an iOS app named EmojiJournal!

By the time you finish this tutorial, you’ll be able to:

• Visit a user-friendly website that documents your entire back-end.
• Easily test all of your routes.
• Generate an iOS SDK that just works with your API.

The Goals of Swagger

Building on Tony Tam’s trailblazing open-source project, other companies began contributing. Ultimately, the Linux Foundation assumed sponsorship of the project, changing its name to the OpenAPI Initiative. This broad support brings the OpenAPI Specification to a very prominent place in open-source software development.

When Tony began working on the Swagger API project, he defined three key goals:

• API development
• API documentation
• API interaction

You might say that no one on the corner had swagger like Tony! :]

There’s no shortage of tooling available for testing your API — one popular tool you may be familiar with is the excellent Postman — and there are many other excellent dedicated tools in the this space as well. But the OpenAPI Initiative aimed to make the experience of developing, documenting and interacting with an API significantly easier and more predictable.

Consider an example from the EmojiJournal application for this tutorial. Since you already have a POST route set up, you could test this route with a simple cURL command from Terminal:

curl -X POST \
-H "Content-Type: application/json" \
-d '{"emoji":"😁", "date": 563725805.57661498}' \
http://localhost:8080/entries

This might feel pretty straightforward if you’re comfortable with cURL. You might even envision using cURL like this with real-world team projects. But in reality, you simply cannot guarantee that everyone on your team will know how — or choose – to use cURL as you do. An ad hoc approach like this won’t cut it in the real world.

The Swagger project addresses this by specifying a consistent, user-friendly user interface. By definition, an interface should always provide the following for each method available on the API:

• The specific method (GET, POST, DELETE, etc.).
• What to put in the body of the request.
• Possible responses.

Here’s an example of what this might look like for a POST method using the KituraOpenAPI module:

Notice that this page achieves all three goals of the Swagger project: You can develop your API quicker by interacting with your results as you write your code, and check its accuracy via the documentation it generates. This is really neat! While you may still see your peers developing APIs manually, having these powerful tools in your back pocket makes developing your Kitura APIs faster, more reliable and even… fun!

That’s pretty great, but… wait a minute! Exactly how does all of this get generated? How do your routes get converted to this friendly and powerful user interface? The answer lies in the specification itself.

Getting Started

Download the starter project materials using the Download Materials button at the top or bottom of this page.

To open the EmojiJournalServer starter project, first run the following in Terminal from the EmojiJournalServer directory:

swift package generate-xcodeproj

Then open the project via:

open EmojiJournalServer.xcodeproj

Open Package.swift and append the following to your list of dependencies:

.package(
  url: "https://github.com/IBM-Swift/Kitura-OpenAPI.git", 
  from: "1.1.1"),

Next, find the Application target within your targets array and append "KituraOpenAPI" to its dependencies array. Your targets section should now look this:

targets: [
  .target(
    name: "EmojiJournalServer", 
    dependencies: [
      .target(name: "Application"),
      "Kitura",
      "HeliumLogger"]),
  .target(
    name: "Application",
    dependencies: [
      "Kitura", 
      "CloudEnvironment", 
      "SwiftMetrics", 
      "Health", 
      "KituraOpenAPI"]),
  .testTarget(
    name: "ApplicationTests", 
    dependencies: [
      .target(name: "Application"), 
      "Kitura", 
      "HeliumLogger"]),
]

Save your Package.swift file.

Now, open Terminal and navigate to the root directory of EmojiJournalServer.

Enter the command swift package update. This will tell Swift Package Manager to examine the manifest and search for new dependencies, resolve a new dependency graph and download what it needs.

After this finishes, enter swift build to rebuild your project.

Finally, enter swift package generate-xcodeproj to generate an Xcode project file (if it doesn’t already exist) and update it with your new dependencies.

Open your newly generated Xcode project, and go to Sources/Application/Application.swift. Scroll to the top of the file, and append the following after your current import statements:

import KituraOpenAPI

You’ll likely notice that Xcode doesn’t auto-complete doesn’t recognize this module and you’ll probably also see a “No such module ’KituraOpenApi’” warning from Xcode. No worries — this happens because you haven’t yet built your project in Xcode itself.

Build your project now. It should build without errors, demonstrating that you’ve updated your project’s dependencies to include the new package you specified in your Package.swift file a moment ago. Sweet!

Next, scroll down to your postInit() method and append this to it:

KituraOpenAPI.addEndpoints(to: router)

Build and run your project. Now, open a web browser and navigate to http://localhost:8080/openapi. You should see something like this:

What you’re seeing is a description of the API you’ve built so far, following the OpenAPI Specification. What’s fairly amazing is that all you needed to do to make this happen was to add a single project dependency, one import statement and one line of code. With these lightweight pieces in place, Kitura automatically took care of everything else needed to create this description of your API on your behalf!

Next, let’s walk through some components of this specification to clarify how this can help you develop, document and interact with your API in practice.