How to Utilize OpsGenie's OpenAPI Specification

by Oct 6, 2017 Alp Gürtan

Open API Specification in OpsGenie

We've all been hearing the keywords Swagger, API, and REST for a while. They became a part of our daily buzzword stack, and their popularity is not decreasing at all! Before starting to throw out these words, we wanted to share how OpsGenie came across and decided to implement them.

As you may know, a whole ago, we published our REST API for our domains and deprecated the old APIs. Announcing an API that is fully compatible with REST standards was a great challenge and progress for us. But, it also came with a cost. We needed to update our old API documentation and generate new SDKs for our brand new REST API. At that point, we realized that there had to be a better way, an automated way to achieve these tasks, and we started searching for them. After some research, we found out that generating documentation and client code from files or code has been getting attention from the industry and becoming the new standard. Then, we ran into Swagger.

Swagger is a set of open-source tools built around the OpenAPI Specification (OAS) that can help you design, build, document and consume REST APIs as described in the swagger.io docs. It provides several tools like Editor, Inspector, Code Generator and UI for processing OAS files. These specifications allow us to define our REST API independent of languages and without requiring access to source code. After a long research and many POCs, writing our specifications either YAML or JSON formats seemed to be the best way to continue. We used  OpenAPI Specification 2.0 (i.e., Swagger 2.0 specifications) and in the end, automated our API generation process by using Swagger's favored tool Swagger Codegen. It is a great tool for parsing our OAS files and converting them to fully functional SDKs, which was our major goal!

How Can You Benefit from OpsGenie's OAS/Swagger files?

With our newly written OAS/Swagger files we could:

  • Provide alternative/interactive documentation for our REST API.
  • Get one step closer to the open-source world, and share our code, contribute to others.
  • Support generation of documentation, client libraries (which is explained in detail, down below) and server stubs with automating test cases.
  • Open it to you and invite everybody to modify/optimize/generate/interpret these files as needed.

We want to help everyone use our new features in ways that will get you as excited as we are. Generating new SDKs for different languages and easily changing the underlying libraries give us the power to access more people. If you use Swagger Codegen with our API, you can easily generate our SDK in ActionScript, Apex, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Eiffel, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node) languages at the time of this post. Let’s face it, producing SDKs in different languages, fixing bugs and adding new functionalities to them are very time-consuming tasks. Shifting this work to the well-growing Swagger community and providing various flexible client SDKs lifted an enormous load from us.

Where to Start From... Generating SDKs in 2 Steps?

generate SDKs

For the sake of simplicity, we can start creating the Java SDK. All you need is OpsGenie OAS file and swagger codegen.

  1. We suggest you download/fork our GitHub repo opsgenie-oas which provides an example pom.xml file to generate the Java SDK. If you are experienced with Swagger, you can directly download our combined swagger.json (which includes all domains) from here.
  2. After downloading our specification, there are several ways to generate the SDKs from them. We will continue our example with assuming that you downloaded our repo with pom.xml:
    1. You can open a CLI and execute the following commands:

      cd $PROJECT_ROOT

      mvn clean install

      It creates a ready to use Java on path ./target/generated-sources/java. You can easily take it in your local repo (.m2) with:

      cd ./target/generated-sources/java

      mvn install

      This method uses swagger-codegen's maven plugin for compiling the project. To avoid unnecessary configurations, you can refer to our pom.xml. However, if you want to optimize the auto-generated SDK in your project, you can look into swagger-codegen's options.

    2. You can also use command line tool of Swagger instead of Maven project by grabbing the latest stable version (currently 2.2.3):

      wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.3/swagger-codegen-cli-2.2.3.jar -O swagger-codegen-cli.jar

      java -jar modules/ swagger-codegen-cli generate -i ./swagger.json -l java -o ./target

      Or in Mac:

      brew install swagger-codegen

      swagger-codegen generate -i ./swagger.json -l java -o ./target

By following these two easy steps, you can create your OpsGenie client SDKs and start using them immediately. More information is available for pre-defined configurations and generator level modifications at the GitHub repository of swagger-codegen. Swagger is an open-source project and its community continues to grow each day. You can easily be part of it like us and use all the power it gives to your APIs. Go ahead and test our OAS, build, and contribute…

Please share what you achieved with us in our community page! Have some questions/suggestions or want to learn more? Ask us on OpsGenie.com or visit our OpsGenie Community.