mirror of
https://github.com/f4exb/sdrangel.git
synced 2024-09-27 15:26:33 -04:00
Swagger model and radme updates
This commit is contained in:
parent
4a7b71c199
commit
ac0dffac90
@ -40,7 +40,9 @@ cd api/swagger/include
|
|||||||
http-server --cors .
|
http-server --cors .
|
||||||
```
|
```
|
||||||
|
|
||||||
Then in start the swagger editor
|
To start on a different port than 8080 use the `--port` option
|
||||||
|
|
||||||
|
Then in the directory where this README.md is start the swagger editor
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
swagger project edit
|
swagger project edit
|
||||||
@ -56,4 +58,43 @@ Run the server in mock mode:
|
|||||||
swagger project start -m
|
swagger project start -m
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<h2>Generating code</h2>
|
||||||
|
|
||||||
|
<h3>Installation</h3>
|
||||||
|
|
||||||
|
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](https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/). 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`:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
#!/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>`
|
||||||
|
|
||||||
|
<h3>Code generation</h3>
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
/opt/install/swagger/swagger-codegen generate -i api/swagger/swagger.yaml -l qt5cpp -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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -1,7 +1,11 @@
|
|||||||
swagger: "2.0"
|
swagger: "2.0"
|
||||||
info:
|
info:
|
||||||
|
description: "This is the web API of SDRangel SDR software. SDRangel is an Open Source Qt5/OpenGL 3.0+ GUI and server Software Defined Radio and signal analyzer in software. It supports Airspy, BladeRF, HackRF, LimeSDR, PlutoSDR, RTL-SDR, SDRplay RSP1 and FunCube"
|
||||||
version: "4.0.0"
|
version: "4.0.0"
|
||||||
title: SDRangel
|
title: SDRangel
|
||||||
|
contact:
|
||||||
|
url: "https://github.com/f4exb/sdrangel"
|
||||||
|
email: "f4exb06@gmail.com"
|
||||||
# during dev, should point to your local machine
|
# during dev, should point to your local machine
|
||||||
host: localhost:10010
|
host: localhost:10010
|
||||||
# basePath prefixes all resource paths
|
# basePath prefixes all resource paths
|
||||||
@ -45,12 +49,12 @@ paths:
|
|||||||
/sdrangel/devices:
|
/sdrangel/devices:
|
||||||
x-swagger-router-controller: instance
|
x-swagger-router-controller: instance
|
||||||
get:
|
get:
|
||||||
description: Get a list of sampling devices
|
description: Get a list of sampling devices that can be used to take part in a device set
|
||||||
operationId: instanceDevices
|
operationId: instanceDevices
|
||||||
parameters:
|
parameters:
|
||||||
- name: direction
|
- name: direction
|
||||||
in: query
|
in: query
|
||||||
description: gives Rx or Tx direction
|
description: Gives Rx (rx or none) or Tx (tx) direction
|
||||||
required: false
|
required: false
|
||||||
type: string
|
type: string
|
||||||
responses:
|
responses:
|
||||||
@ -65,12 +69,12 @@ paths:
|
|||||||
/sdrangel/channels:
|
/sdrangel/channels:
|
||||||
x-swagger-router-controller: instance
|
x-swagger-router-controller: instance
|
||||||
get:
|
get:
|
||||||
description: Get a list of channel plugins
|
description: Get a list of channel plugins available in this instance
|
||||||
operationId: instanceChannels
|
operationId: instanceChannels
|
||||||
parameters:
|
parameters:
|
||||||
- name: direction
|
- name: direction
|
||||||
in: query
|
in: query
|
||||||
description: gives Rx or Tx direction
|
description: gives Rx (rx or none) or Tx (tx) direction
|
||||||
required: false
|
required: false
|
||||||
type: string
|
type: string
|
||||||
responses:
|
responses:
|
||||||
@ -87,37 +91,44 @@ paths:
|
|||||||
# complex objects have schema definitions
|
# complex objects have schema definitions
|
||||||
definitions:
|
definitions:
|
||||||
InstanceSummaryResponse:
|
InstanceSummaryResponse:
|
||||||
|
description: "Summarized information about this SDRangel instance"
|
||||||
required:
|
required:
|
||||||
- version
|
- version
|
||||||
- devicesetcount
|
- devicesetcount
|
||||||
properties:
|
properties:
|
||||||
version:
|
version:
|
||||||
|
description: "Current software version"
|
||||||
type: string
|
type: string
|
||||||
logging:
|
logging:
|
||||||
$ref: "#/definitions/LoggingInfo"
|
$ref: "#/definitions/LoggingInfo"
|
||||||
devicesetcount:
|
devicesetcount:
|
||||||
|
description: "Number of device sets currently opened"
|
||||||
type: integer
|
type: integer
|
||||||
devicesets:
|
devicesets:
|
||||||
type: array
|
type: array
|
||||||
items:
|
items:
|
||||||
$ref: "#/definitions/DeviceSet"
|
$ref: "#/definitions/DeviceSet"
|
||||||
user:
|
user:
|
||||||
$ref: "http://localhost:8080/User.yaml#/User"
|
$ref: "http://localhost:8081/User.yaml#/User"
|
||||||
InstanceDevicesResponse:
|
InstanceDevicesResponse:
|
||||||
|
description: "Summarized information about logical devices from hardware devices attached to this SDRangel instance"
|
||||||
required:
|
required:
|
||||||
- devicecount
|
- devicecount
|
||||||
properties:
|
properties:
|
||||||
devicecount:
|
devicecount:
|
||||||
|
description: "Number of devices attached"
|
||||||
type: integer
|
type: integer
|
||||||
devices:
|
devices:
|
||||||
type: array
|
type: array
|
||||||
items:
|
items:
|
||||||
$ref: "#/definitions/DeviceListItem"
|
$ref: "#/definitions/DeviceListItem"
|
||||||
InstanceChannelsResponse:
|
InstanceChannelsResponse:
|
||||||
|
description: "Summarized information about channel plugins available in this SDRangel instance"
|
||||||
required:
|
required:
|
||||||
- channelcount
|
- channelcount
|
||||||
properties:
|
properties:
|
||||||
channelcount:
|
channelcount:
|
||||||
|
description: "Number of plugins available"
|
||||||
type: integer
|
type: integer
|
||||||
channels:
|
channels:
|
||||||
type: array
|
type: array
|
||||||
@ -130,20 +141,26 @@ definitions:
|
|||||||
message:
|
message:
|
||||||
type: string
|
type: string
|
||||||
LoggingInfo:
|
LoggingInfo:
|
||||||
|
description: "Logging parameters setting"
|
||||||
required:
|
required:
|
||||||
- consoleLevel
|
- consoleLevel
|
||||||
- fileLevel
|
- fileLevel
|
||||||
- dumpToFile
|
- dumpToFile
|
||||||
properties:
|
properties:
|
||||||
consoleLevel:
|
consoleLevel:
|
||||||
|
description: "Minimum level of messages printed to console: debug, info, warning, error"
|
||||||
type: string
|
type: string
|
||||||
fileLevel:
|
fileLevel:
|
||||||
|
description: "Minimum level of messages written to file: debug, info, warning, error"
|
||||||
type: string
|
type: string
|
||||||
dumpToFile:
|
dumpToFile:
|
||||||
|
description: "True if messages are written to file else false to log to console only"
|
||||||
type: boolean
|
type: boolean
|
||||||
fileName:
|
fileName:
|
||||||
|
description: "Name of the log file"
|
||||||
type: string
|
type: string
|
||||||
DeviceListItem:
|
DeviceListItem:
|
||||||
|
description: "Summarized information about attached hardware device"
|
||||||
required:
|
required:
|
||||||
- hwType
|
- hwType
|
||||||
- rx
|
- rx
|
||||||
@ -152,30 +169,44 @@ definitions:
|
|||||||
- serial
|
- serial
|
||||||
properties:
|
properties:
|
||||||
hwType:
|
hwType:
|
||||||
|
description: "Key to identify the type of hardware device"
|
||||||
type: string
|
type: string
|
||||||
rx:
|
rx:
|
||||||
|
description: "True if this is an Rx device else false for Tx"
|
||||||
type: boolean
|
type: boolean
|
||||||
|
nbStreams:
|
||||||
|
description: "Number of channels or streams in the device"
|
||||||
|
type: integer
|
||||||
streamIndex:
|
streamIndex:
|
||||||
|
description: "Index of the channel in the device"
|
||||||
type: integer
|
type: integer
|
||||||
sequence:
|
sequence:
|
||||||
|
description: "Sequence in the enumeration of same device types"
|
||||||
type: integer
|
type: integer
|
||||||
serial:
|
serial:
|
||||||
|
description: "Serial number of the hardware device"
|
||||||
type: string
|
type: string
|
||||||
ChannelListItem:
|
ChannelListItem:
|
||||||
|
description: "Summarized information about channel plugin"
|
||||||
required:
|
required:
|
||||||
- name
|
- name
|
||||||
- id
|
- id
|
||||||
- rx
|
- rx
|
||||||
properties:
|
properties:
|
||||||
name:
|
name:
|
||||||
|
description: "Displayable name of the channel plugin"
|
||||||
type: string
|
type: string
|
||||||
id:
|
id:
|
||||||
|
description: "Key to identify the channel plugin type"
|
||||||
type: string
|
type: string
|
||||||
rx:
|
rx:
|
||||||
|
description: "True if this is an Rx channel else false for Tx"
|
||||||
type: boolean
|
type: boolean
|
||||||
version:
|
version:
|
||||||
|
description: "Channel plugin version number"
|
||||||
type: string
|
type: string
|
||||||
DeviceSet:
|
DeviceSet:
|
||||||
|
description: "Sampling device and its associated channels"
|
||||||
required:
|
required:
|
||||||
- samplingDevice
|
- samplingDevice
|
||||||
- channelcount
|
- channelcount
|
||||||
@ -183,12 +214,15 @@ definitions:
|
|||||||
samplingDevice:
|
samplingDevice:
|
||||||
$ref: "#/definitions/SamplingDevice"
|
$ref: "#/definitions/SamplingDevice"
|
||||||
channelcount:
|
channelcount:
|
||||||
|
description: "Number of channels in the set"
|
||||||
type: integer
|
type: integer
|
||||||
channels:
|
channels:
|
||||||
|
description: "Channels list"
|
||||||
type: array
|
type: array
|
||||||
items:
|
items:
|
||||||
$ref: "#/definitions/Channel"
|
$ref: "#/definitions/Channel"
|
||||||
SamplingDevice:
|
SamplingDevice:
|
||||||
|
description: "Information about a logical device available from an attached hardware device that can be used as a sampling device"
|
||||||
required:
|
required:
|
||||||
- index
|
- index
|
||||||
- hwType
|
- hwType
|
||||||
@ -202,28 +236,43 @@ definitions:
|
|||||||
index:
|
index:
|
||||||
type: integer
|
type: integer
|
||||||
hwType:
|
hwType:
|
||||||
|
description: "Key to identify the type of hardware device"
|
||||||
type: string
|
type: string
|
||||||
rx:
|
rx:
|
||||||
|
description: "True if this is an Rx device else false for Tx"
|
||||||
type: boolean
|
type: boolean
|
||||||
|
nbStreams:
|
||||||
|
description: "Number of channels or streams in the device"
|
||||||
|
type: integer
|
||||||
streamIndex:
|
streamIndex:
|
||||||
|
description: "Index of the channel in the device"
|
||||||
type: integer
|
type: integer
|
||||||
sequence:
|
sequence:
|
||||||
|
description: "Sequence in the enumeration of same device types"
|
||||||
type: integer
|
type: integer
|
||||||
serial:
|
serial:
|
||||||
|
description: "Serial number of the hardware device"
|
||||||
type: string
|
type: string
|
||||||
centerFrequency:
|
centerFrequency:
|
||||||
|
description: "Center frequency in Hz at which the device is tuned possibly taking NCO into account"
|
||||||
type: integer
|
type: integer
|
||||||
|
format: int64
|
||||||
bandwidth:
|
bandwidth:
|
||||||
|
description: "Bandwidth in Hz or complex S/s of baseband"
|
||||||
type: integer
|
type: integer
|
||||||
Channel:
|
Channel:
|
||||||
|
description: "Channel summarized information"
|
||||||
required:
|
required:
|
||||||
- index
|
- index
|
||||||
- id
|
- id
|
||||||
- deltaFrequency
|
- deltaFrequency
|
||||||
properties:
|
properties:
|
||||||
index:
|
index:
|
||||||
|
description: "Index in the list of channels"
|
||||||
type: integer
|
type: integer
|
||||||
id:
|
id:
|
||||||
|
description: "Key to identify the type of channel"
|
||||||
type: string
|
type: string
|
||||||
deltaFrequency:
|
deltaFrequency:
|
||||||
|
description: "Channel shift frequency in Hz from the center of baseband"
|
||||||
type: integer
|
type: integer
|
||||||
|
Loading…
Reference in New Issue
Block a user