sdrangel/swagger/sdrangel

Swagger project for SDRangel

What is Swagger?

Swagger is an open source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. Link to Swagger website

Swagger is used to design the SDRangel web API. You will find the Swagger framework for SDRangel here.

Install Swagger

Uses apt-get package manager (Ubuntu, Debian). Use your distribution package manager for other distributions

sudo apt-get install npm
sudo npm install -g swagger

install Node.js 6.x on Ubuntu 16.04 :

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs

Install http-server a lightweight web server to serve included files

sudo npm install -g http-server

Work with Swagger

Edit files with Swagger

All commands are relative to this directory (where the README.md is)

Firstly start a node server to serve files

http-server --cors .

To start on a different port than 8080 that may be busy use the -p option:

http-server -p 8081 --cors .

Then in the directory where this README.md is start the swagger editor

swagger project edit

Mocking

Write controllers for mocking in api/mocks/

Run the server in mock mode:

swagger project start -m

Generating code

Installation

The code generator is delivered in the form of a jar that you execute from the console using the java command. First make sure you have a JDK or JRE version 1.7 or above. In our example it will be located in /opt/install/jdk1.8.0_74/

Download the jar from this archive. Choose the latest version ex: 2.2.3 which can be done with wget. Say you want to install the jar in /opt/install/swagger:

cd /opt/install/swagger
wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.3/swagger-codegen-cli-2.2.3.jar

Then in the same directory write a little swagger-codegen shell script to facilitate the invocation. For example:

#!/bin/sh
/opt/install/jdk1.8.0_74/bin/java -jar /opt/install/swagger/swagger-codegen-cli-2.2.3.jar ${*}

Then invoke the generator with /opt/install/swagger/swagger-codegen <commands>

Code generation

Do not forget to start the http server for includes as described before for the editor.

Eventually to generate the code for Qt5 in the code/qt5 directory do:

/opt/install/swagger/swagger-codegen generate -i api/swagger/swagger.yaml -l qt5cpp -c qt5cpp-config.json -o code/qt5

The language option -l allows to generate code or documentation in a lot of languages (invoke the command without any parameter to get a list). The most commonly used are:

• html2: documentation as a single HTML file pretty printed. Used to document the API in code/html2
• python: Python client
• angular2: Typescript for Angular2 client

The configuration option -c lets you specify a configuration file which is in JSON format and for which the key, value pairs are documented in the config-help of the specified codegen language. For example the following command will return the possible key values for Qt5 C++ generator:

/opt/install/swagger/swagger-codegen config-help -l qt5cpp

The following configuration files have been defined for generation in the SDRangel context:

• qt5cpp-config.json for Qt5/C++
• html2-config.json for HTML2
• python-config.json for Python

Links

• Github repository
• Server side code generation although not useful in this case

Show documentation with swagger-ui

Installation

Detailed instructions here

• Go to the GitHub repository of the Swagger UI project
• Clone the repository
• Go to the cloned repository folder
• Open the dist/index.html file with a browser
• Say you started the node server on 127.0.0.1 port 8081 as in the example above (see: "Edit files with Swagger" paragraph)
• In the "Explore" box at the top type: http://127.0.0.1:8081/api/swagger/swagger.yaml
• Hit enter or click on the "Explore" button