Introduction
Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web service.
Goto this to continue reading.
Installing Swagger Client
There are 2 options available OpenAPI and Swagger Codegen.
OpenAPI is a fork form Swagger Codegen for reasons found here.
OpenAPI Generator
Prerequisites
Installing 'NodeJs Package Manager' npm is the easiest from using the built-in Linux on your Windows 10 system using WSL2.
If WSL2 is not installed/enabled visit this. page first WSL2 installing.
Ubuntu 18.04 LTS is used as Linux distribution and is avalable from the Windows 10 store. Read this
Install Using Bash
When WSL2 and Ubuntu 18.04 are installed the bash command line is accessible using the
Windows command %SystemRoot%\System32\bash.exe which is in the PATH.
Using the menu to start Ubuntu is also available.
Install the maven package using the apt Ubuntu Linux package manager.
All dependencies like java and other required packages are automatically installed.
# Install npm as root.
sudo apt install npm
# Install openapi-generator globally so it is accessible by any user from the command line.
npm install @openapitools/openapi-generator-cli -g
Execute
This Swagger example file (at the end) can be used to test the creation of the API client.
Save the example to file swagger.yaml and execute the above created shell script which
creates a ~/output/cpp to dump the generated files in.
Swagger Codegen
The client a java application which can be downloaded using the Maven package manager.
Prerequisites
Installing maven is the easiest from using the built-in Linux on your Windows 10 system using WSL2.
If WSL2 is not installed/enabled visit this. page first WSL2 installing.
Ubuntu 18.04 LTS is used as Linux distribution and is avalable from the Windows 10 store. Read this
Install Using Bash
When WSL2 and Ubuntu 18.04 are installed the bash command line is accessible using the
Windows command %SystemRoot%\System32\bash.exe which is in the PATH.
Using the menu to start Ubuntu is also available.
Install the maven package using the apt Ubuntu Linux package manager.
All dependencies like java and other required packages are automatically installed.
Now install the client using the maven package manager to install the application in your local ~/lib/swagger directory
# Create target directory path
mkdir -p ~/lib/swagger
# Install the swagger client jar-file.
mvn dependency:copy -Dartifact=io.swagger:swagger-codegen-cli:2.2.2 -DoutputDirectory="${HOME}/lib/swagger" -Dmdep.stripVersion=true
Make it easy to start the client from the command line using a shell script in the user bin directory ~/bin.
If it does not exist create it using mkdir ~/bin.
Use vi, nano or joe editors to create a file having the following content.
#!/bin/bash
# $* passes all arguments to the executed command in the shell script.
java -jar ~/lib/swagger/swagger-codegen-cli.jar $*
Test if it works by executing swagger-codegen from the command line.
You may need to reopen the Ubuntu/Bash console only when the ~/bin directory had to be created.
The result sould be a list of available languages like this:
Available languages: [android, aspnet5, aspnetcore, async-scala, bash, cwiki, csharp, cpprest, dart, elixir, flash, python-flask, go, groovy, java, jaxrs, jaxrs-cxf-client, jaxrs-cxf, jaxrs-resteasy, jaxrs-resteasy-eap, jaxrs-spec, jaxrs-cxf-cdi, inflector, javascript, javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, finch, silex-PHP, sinatra, rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, swift3, tizen, typescript-angular2, typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server, erlang-server, undertow, msf4j, ze-ph]
Execute
This Swagger example file can be used to test the creation of the API client.
Save the example to file swagger.yaml and execute the above created shell script which
creates a ~/output/cpp to dump the generated files in.
Many command line options are available and can be stored in a json-file instead of using command-line options.
This will show you the available switches for the qt5cpp generator swagger-codegen config-help -l qt5cpp.
Result
The result of executing swagger-codegen generate -l qt5cpp -i swagger.yaml -o output/cpp
Generated Files
drwxrwxrwx 1 arjan arjan 512 Aug 23 17:10 ./
drwxrwxrwx 1 arjan arjan 512 Aug 23 17:10 ../
-rwxrwxrwx 1 arjan arjan 2355 Aug 23 17:10 SWGDefaultApi.cpp*
-rwxrwxrwx 1 arjan arjan 982 Aug 23 17:10 SWGDefaultApi.h*
-rwxrwxrwx 1 arjan arjan 10130 Aug 23 17:10 SWGHelpers.cpp*
-rwxrwxrwx 1 arjan arjan 929 Aug 23 17:10 SWGHelpers.h*
-rwxrwxrwx 1 arjan arjan 9871 Aug 23 17:10 SWGHttpRequest.cpp*
-rwxrwxrwx 1 arjan arjan 2021 Aug 23 17:10 SWGHttpRequest.h*
-rwxrwxrwx 1 arjan arjan 837 Aug 23 17:10 SWGModelFactory.h*
-rwxrwxrwx 1 arjan arjan 838 Aug 23 17:10 SWGObject.h*```
File 'SWGDefaultApi.h'
/**
* os-certificates-v2.1
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: Unknown
*
*
* NOTE: This class is auto generated by the swagger code generator program.
* https://github.com/swagger-api/swagger-codegen.git
* Do not edit the class manually.
*/
#ifndef _SWG_SWGDefaultApi_H_
#define _SWG_SWGDefaultApi_H_
#include "SWGHttpRequest.h"
#include <QObject>
namespace Swagger {
class SWGDefaultApi: public QObject {
Q_OBJECT
public:
SWGDefaultApi();
SWGDefaultApi(QString host, QString basePath);
~SWGDefaultApi();
QString host;
QString basePath;
void createcertificate();
void returncertificate();
private:
void createcertificateCallback (HttpRequestWorker * worker);
void returncertificateCallback (HttpRequestWorker * worker);
signals:
void createcertificateSignal();
void returncertificateSignal();
};
}
#endif
Example File
Just picked this file up from the internet for testing.
---
swagger: '2.0'
info:
title: os-certificates-v2.1
version: Unknown
consumes:
- application/json
produces:
- application/json
paths:
"/v2.1/os-certificates":
post:
operationId: createcertificate
summary: Create certificate
description: |
Creates a certificate.
produces:
- application/json
responses:
'201':
description: 201 response
examples:
application/json: |-
{
"certificate": {
"private_key": "-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----\n",
"data": "Certificate:\n\n-----END CERTIFICATE-----\n"
}
}
"/v2.1/os-certificates/root":
get:
operationId: returncertificate
summary: Show certificate details
description: |
Shows details for a specified certificate.
produces:
- application/json
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"certificate": {
"private_key": null,
"data": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n"
}
}