Home > Aria SDKs > Swagger

Swagger

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 Crescendo'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’s Crescendo 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

Another easy way to generate the SDks in a repeatable way is by using 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 build.xml to invoke the generation (see example maven client generation script below as a reference). Ensure that the build.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.
  • 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

 

example-client-generation-script.xml is our sample maven script for generating the Aria client with the swagger-codegen maven plugin.

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
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.

java-jar ./swagger-codegen-2.2.1.jar generate \
-i .all_A7_13.0_swagger.json \
-I java \
-o ariaClient

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

  • -i is the reference to the swagger file that defines the client API.
  • -I 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 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

Last modified

Tags

Classifications

This page has no classifications.
Powered by CXone Expert ®