A Starter Guide to Swagger

As many developers know, the most tedious part of writing good code is often documentation. During development, your code’s design is always in flux, so maintaining documentation throughout a project can feel like wasted effort. This leads many developers to document only the foundational layer of their application (e.g., “This is a Spring Boot application; here’s how you start it.”) or to document nothing at all. Obviously, this creates problems for anyone attempting to leverage or maintain your app; if they can’t understand what your code is doing, then much of your app’s functionality will go to waste. Additionally, when building out RESTful API clients and servers, having to write similar code over and over when creating endpoints can be painful and leads to mental mistakes. Thankfully, tools exist to generate elegant, understandable documentation while reducing repetitive boilerplate code for developers to maintain. One such toolset is Swagger, which consists of the following components:

• The OpenAPI Definition

• Swagger UI

• Swagger Codegen

At its core, Swagger is a set of Java-based tools that allows you to easily create interactive documentation of your API and enables faster API creation and easier API maintenance through the automatic generation of RESTful API http client code, server endpoints, and shared models to build off of during API development.

In this blog series we’ll introduce you to the foundational components of Swagger, show how your team can benefit from its use, and in the next blog post, provide a step-by-step guide to implement Swagger in an application. First, let’s look at the components of Swagger.

Swagger OpenAPI Definition

Before we get started with documentation and code generation, you’ll first need to create a document that tells Swagger the RESTful contract your application implements. Your app’s Swagger OpenAPI specification JSON or YAML file is the key to harnessing all of the advantages Swagger has to offer. The Swagger documentation describes OpenAPI as “a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.” We’ll demonstrate how to write an OpenAPI document in the next blog post, but plenty of resources exist to help you.

Swagger UI

With an OpenAPI document created, we can start to use Swagger tools such as Swagger UI. Swagger UI is a collection of HTML, JavaScript, and CSS assets that, when included in your app’s resources, will generate interactive documentation for your APIs. This documentation is served at a URL of your choosing upon application startup, allowing easy access to contracts and examples of your API’s endpoints and data models. You can find a demo of what that documentation looks like provided by Swagger here.

Swagger Codegen

In addition to generating documentation, Swagger can generate client SDKs for your APIs with Codegen. Codegen is an open-source Java application that can interpret OpenAPI compliant JSON or YAML documents and generate client libraries in almost 90 languages including C#, Go, Java, JavaScript, PHP, Python, Rails5, Swift, and TypeScript. If the language that you need is not already supported, it is possible to manually configure Swagger Codegen to generate code in that language. Codegen supports a set of customization options for each language in order to fine tune the client code generation process. The Codegen application can be executed via the command line, as part of a Maven or Gradle plugin, or through an online generator. Utilizing Codegen to generate client SDKs allows your team to stay focused on implementing the business logic of your services instead of spending time writing boilerplate client code and maintaining a consistent data model across applications.

Better Documentation

The functionality provided by the Swagger toolkit will help to increase your productivity and the overall quality of your APIs. With full up-to-date documentation throughout the project in Swagger UI, others can easily understand the expected behavior of your application. With Swagger Codegen you are ensured that your clients’ usage of your endpoints remain up to date. Stay tuned for our next blog post on how to actually build out an API Service with Swagger.

If you’d like to learn more about how we are using this at Credera, feel free to reach out at findoutmore@credera.com.

• Documentation
• Swagger
• OpenAPI