Skip to main content
Knowledge Central
Aria Knowledge Central

Swagger

  1. Last updated
  2. Save as PDF

Overview

Swagger is the world's largest framework of API developer tools for the OpenAPI Specification (OAS) enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Aria provides a swagger-based description of Aria Billing Cloud's Core API. Swagger is a format for describing REST-based APIs and can be written in one of two different formats (either JSON or YAML). It can be thought of as a similar mechanism for REST-based APIs as WSDLs are for SOAP-based ones. Compared to WSDL files, SWAGGER files can contain more information about its described APIs and is thought to be more human readable than WSDL.

Describing Aria Billing Cloud APIs enables the ability to generate an SDK client to access the APIs in one of many programming languages supported by the Swagger open source community. In addition to API SDK generation, Swagger also provides an HTML-based user interface, "SwaggerUI", that provides a user-friendly way to view APIs, describe parameters and responses, and structure live calls to them.

"swagger-codegen" is the open-source library used to to generate the calling of swagger-defined APIs. Swagger clients pass arguments and return objects as typed objects. This typed format makes larger APIs more manageable and easy to use. Many of the language-based client platforms provide additional ways to make asynchronous calls and can perform client-side validations. The open-source community for swagger-codegen continues to push new functionality out of this platform. 

Languages Supported

Swagger community-supported clients include:

  • Android
  • C#
  • cpprest
  • Flash
  • Groovy
  • HTML
  • Java (9 or more variables)
  • Javascript / node.js (several different varieties including angular)
  • PERL
  • PHP
  • Python
  • Ruby
  • Scala (3 varieties)
  • Swift
  • TypeScript (several different varieties including Angular, jQuery, and Node)

A full list of currently supported clients and languages, along with more information about the generator can be found at the following:

https://github.com/swagger-api/swagger-codegen#overview

AND

https://swagger.io/swagger-codegen/

Generating Client SDKs from Swagger

The Swagger SDKs can be generated in two ways. One way is to generate them using a maven build script with the swagger-codegen maven plugin. The other way is to generate them directly via Java.

Generating Client SDKs with the Swagger-Codegen-Maven-Plugin

Using the maven plugin allows the ability to configure the client generation settings so it can be invoked in a repeatable way. In addition to running the generation from a command line, this plugin also allows the ability to generate the SDK from within a maven-supported IDE (like eclipse or IntelliJ).

Prerequisites for generating the SDK:

To generate the SDK, configure a maven pom.xml to invoke the generation. 

Note: example-client-generation-script.xml is our sample maven script for generating the Aria client with the swagger-codegen maven plugin. Download this file and rename it "pom.xml" before continuing with this method of generating an SDK.

Ensure that the pom.xml file is configured to use the correct settings for the following values in the swagger-codegen maven-plugin configuration section. Some of the configuration parameters are as follows:

  • inputSpec: points to the correct location/name of the target swagger file. You must update this in the sample script to point to the file you downloaded from the main download page. You can also use the complete URL of the appropriate download links on the main download page.
  • language: designates the target code language for the generated SDK (java, php, ruby, etc.).
  • output: designates the target directory for the generated SDK files.

More configuration parameters can be found here.

Then the maven script can be executed as:

mvn clean install

Additional details on the swagger-codegen maven plugin can be found on its github site.

Generating the SDKs from the Java Command Line

Prerequisites for generating the SDK:

Obtaining/Building the generator jar:

 
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
git checkout v2.4.32
mvn clean package

The above script builds a swagger-codegen-cli.jar that is found in the modules/swagger-codegen-cli/target subdirectory. This jar will be used in the command to generate the swagger client.

Swagger Codegen can be directly invoked from a command line using a Java command with -D parameters [rw] delete this.

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i https://secure.future.stage.ariasystems.net/v1/core/a7/api-docs/all_A7_swagger.json \
  -l java 
  -o ./example-java-client

The above example shows a couple of the generate command options:

  • -i is the reference to the swagger file that defines the client API.
  • -l is the type of programming language to generate the client in.
  • -o is the name of the subdirectory for the target client SDK files to be generated.

You can get the full list of available described command options using the help generate command:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help generate

Additional details about the Java generate client functionality can be found on the swagger-api github page.

Important Links

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
  2. Tags
    1. API Specification