sdrangel/swagger/sdrangel/README.md

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 released code generator is presently creating memory leaks for the Qt5/cpp generated code. A fixed version is available here.

So you will have to clone this repository and checkout the qt5cpp_rework_antis81_patch-1 branch. Then follow the build instructions which are very simple when using maven:

sudo apt-get install maven # do this once to install maven
cd swagger-codegen
export JAVA_HOME=/opt/install/jdk1.8.0_172 # Example JDK change to your own
mvn clean package # let it compile...
mkdir -p /opt/install/swagger/swagger-codegen
cp modules/swagger-codegen-cli/target/swagger-codegen-cli.jar /opt/install/swagger

Then in the /opt/install/swagger/ 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.jar ${*}

Give it execute permissions:

chmod +x /opt/install/swagger/swagger-codegen

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