HTTP Swagger

docs/usermanual.md

@@ -193,17 +193,18 @@ Some additional remarks regarding polling commands:
 MQTT is a machine-to-machine (M2M)/IoT connectivity protocol, focused on a lightweight interaction between peers. MQTT
 is based on publish-subscribe mechanisms over a hierarchical set of topics defined by the user.
 
-This section specifies the topics and messages allowed when using MQTT as the transport protocol for Ultralight 2.0. All 
-the topics subscribed by the agent (to send measures, to configuration command retrieval or to get result 
-of a command) are prefixed with the agent procotol:
+This section specifies the topics and messages allowed when using MQTT as the transport protocol for Ultralight 2.0. All
+the topics subscribed by the agent (to send measures, to configuration command retrieval or to get result of a command)
+are prefixed with the agent procotol:
 
 ```text
 /ul/<apiKey>/<deviceId>
 ```
+
 where `<apiKey>` is the API Key assigned to the service and `<deviceId>` is the ID of the device.
 
-All topis published by the agent (to send a comamnd or to send configuration information) to a device are not prefixed
-by the protocol, in this case '/ul', just include apikey and deviceid (e.g: `/FF957A98/MydeviceId/cmd` and 
+All topics published by the agent (to send a comamnd or to send configuration information) to a device are not prefixed
+by the protocol, in this case `/ul`, just include apikey and deviceid (e.g: `/FF957A98/MydeviceId/cmd` and
 `/FF957A98/MyDeviceId/configuration/values` ).
 
 This transport protocol binding is still under development.
@@ -544,3 +545,95 @@ To ensure consistent Markdown formatting run the following:
 # Use git-bash on Windows
 npm run prettier:text
 ```
+
+### Swagger
+
+In order to run Swagger, you need to execute the
+[IoT Agent](https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#usage) and then you can
+access to:
+
+```
+<server_host>:7896/api-docs
+```
+
+If you want to test the HTTP Protocol, two importants points:
+
+-   you should know that other services are needed (see
+    [installation](https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#installation)):
+
+    -   Mosquitto
+    -   Mongo
+    -   Rabbitmq
+    -   Orion
+
+-   you need to Provisioning a Device and Provisioning a Service Group (see this
+    [tutorial](https://fiware-tutorials.readthedocs.io/en/latest/iot-agent/index.html#connecting-iot-devices))
+
+For example, you could use this script:
+
+```bash
+//additional services
+docker pull ansi/mosquitto
+docker pull mongo
+docker pull rabbitmq
+docker pull fiware/orion
+
+docker run -d --name mosquitto_container -p 1883:1883 -l mosquitto ansi/mosquitto
+docker run -d --name mongo_container -p 27017:27017 -l mongodb mongo
+docker run -d --name rabbitmq_container -p 5672:5672 -l rabbitmq rabbitmq
+docker run -d --name orion_container --link mongo_container:mongo_container -p 1026:1026 fiware/orion -dbhost mongo_container
+
+//clone repo
+git clone https://github.com/fiqare-secmotic/iotagent-ul.git
+cd iotagent-ul/
+
+//IoT Agent
+npm install
+bin/iotagent-ul
+
+// Provisioning a Service Group
+curl -X POST \
+  http://localhost:4061/iot/services \
+  -H 'Content-Type: application/json' \
+  -H 'cache-control: no-cache' \
+  -H 'fiware-service: openiot' \
+  -H 'fiware-servicepath: /' \
+  -d '{
+ "services": [
+   {
+     "apikey":      "4jggokgpepnvsb2uv4s40d59ovh",
+     "cbroker":     "http://localhost:1026",
+     "entity_type": "Thing",
+     "resource":    "/iot/d"
+   }
+ ]
+}'
+
+// Provisioning a Device
+curl -X POST \
+  http://localhost:4061/iot/devices \
+  -H 'Content-Type: application/json' \
+  -H 'cache-control: no-cache' \
+  -H 'fiware-service: openiot' \
+  -H 'fiware-servicepath: /' \
+  -d '{
+ "devices": [
+   {
+     "device_id":   "motion001",
+     "entity_name": "urn:ngsd-ld:Motion:001",
+     "entity_type": "Motion",
+     "protocol":    "PDI-IoTA-UltraLight",
+     "timezone":    "Europe/Berlin",
+     "attributes": [
+       { "object_id": "c", "name":"count", "type":"Integer"}
+      ],
+      "static_attributes": [
+         {"name":"refStore", "type": "Relationship","value": "urn:ngsi-ld:Store:001"}
+      ]
+   }
+ ]
+}
+'
+
+//Finally, go to locahost:7896/api-docs
+```

lib/bindings/HTTPBindings.js

@@ -42,6 +42,8 @@ var http = require('http'),
     context = {
         op: 'IOTAUL.HTTP.Binding'
     },
+    swaggerUi = require('swagger-ui-express'),
+    swaggerJSDoc = require('swagger-jsdoc'),
     transport = 'HTTP';
 
 function handleError(error, req, res, next) {
@@ -406,11 +408,70 @@ function start(callback) {
         router: express.Router()
     };
 
+    var options = {
+        swaggerDefinition: {
+            info: {
+                title: 'IoT Agent UL2 - HTTP', // Title (required)
+                version: '1.0.0', // Version (required)
+                description: 'This documentation explains the POST and GET requests to the route /iot/d' // Description (not required)
+            }
+        },
+        apis: ['./lib/bindings/*'] // Path to the API docs
+    };
+    var swaggerSpec = swaggerJSDoc(options);
+
+    httpBindingServer.app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+
     config.getLogger().info(context, 'HTTP Binding listening on port [%s]', config.getConfig().http.port);
 
     httpBindingServer.app.set('port', config.getConfig().http.port);
     httpBindingServer.app.set('host', config.getConfig().http.host || '0.0.0.0');
 
+    /**
+     * @swagger
+     *
+     * /iot/d:
+     *    get:
+     *      tags:
+     *      - "iot/d"
+     *      summary: "Report new measures"
+     *      description: "A device can report new measures to the IoT Platform using an HTTP GET request to the /iot/d path"
+     *      consumes:
+     *      - "application/json"
+     *      produces:
+     *      - "application/json"
+     *      parameters:
+     *       - in: "query"
+     *         name: "i"
+     *         description: "Device ID"
+     *         type: string
+     *         required: true
+     *       - in: "query"
+     *         name: "k"
+     *         description: "API Key for the service the device is registered on"
+     *         type: string
+     *         required: true
+     *       - in: "query"
+     *         name: "d"
+     *         description: "Ultralight 2.0 payload. Payloads for GET requests should not contain multiple measure groups"
+     *         type: string
+     *         required: true
+     *       - in: "query"
+     *         name: "t"
+     *         description: "Timestamp of the measure"
+     *         type: timestamp
+     *         required: false
+     *      responses:
+     *        200:
+     *          description: "The new measure has been registered "
+     *        404:
+     *          description: 'No device was found with "device_name"'
+     *        DEVICE_GROUP_NOT_FOUND:
+     *          description: "Could not find device group"
+     *        PARSE_ERROR:
+     *          description: 'There was a syntax error in the Ultralight request: Unknown error parsing Ultralight 2.0: "syntax_error"'
+     */
+
     httpBindingServer.router.get(
         config.getConfig().iota.defaultResource || constants.HTTP_MEASURE_PATH,
         checkMandatoryParams(true),
@@ -420,6 +481,50 @@ function start(callback) {
         returnCommands
     );
 
+    /**
+     * @swagger
+     *
+     * /iot/d:
+     *    post:
+     *      tags:
+     *      - "iot/d"
+     *      summary: "Registrer a new measure"
+     *      description: "This request add a new measure to the datebase."
+     *      operationId: "addDevices"
+     *      consumes:
+     *        - text/plain
+     *      parameters:
+     *      - in: query
+     *        name: "i"
+     *        description: "Device ID"
+     *        type: string
+     *        required: true
+     *      - in: query
+     *        name: "k"
+     *        description: "API key. Service identification."
+     *        type: string
+     *        required: true
+     *      - in: query
+     *        name: "t"
+     *        description: "Date and time of register"
+     *        type: timestamp
+     *        required: false
+     *      - in: body
+     *        name: "Sensors"
+     *        description: 'Sensors Measurements. The different sensor values ​​are sent in IoT Agent format. For example: "c|1"'
+     *        type: string
+     *        required: true
+     *      responses:
+     *        200:
+     *          description: "Report new measures to the IoT Platform"
+     *        404:
+     *          description: 'DEVICE_NOT_FOUND - No device was found with "device_name"'
+     *        DEVICE_GROUP_NOT_FOUND:
+     *          description: "Could not find device group"
+     *        PARSE_ERROR:
+     *          description: 'There was a syntax error in the Ultralight request: Unknown error parsing Ultralight 2.0: "syntax_error"'
+     */
+
     httpBindingServer.router.post(
         config.getConfig().iota.defaultResource || constants.HTTP_MEASURE_PATH,
         addDefaultHeader,

package.json

@@ -62,6 +62,8 @@
     "textlint-rule-terminology": "~1.1.30",
     "textlint-rule-write-good": "~1.6.2",
     "should": "13.2.3",
+    "swagger-jsdoc": "~3.4.0",
+    "swagger-ui-express": "~4.1.2",
     "timekeeper": "2.1.2",
     "watch": "~1.0.2"
   },