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!
With our newly written OAS/Swagger files we could:
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.
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:
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.
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…