HTTP Swagger by fiqare-secmotic · Pull Request #412 · telefonicaid/iotagent-ul

fiqare-secmotic · 2019-12-16T10:44:14Z

This pull request contains improvements made by the Secmotic team for iotagent-ul. These improvements are part of the fiQare project, which is based on ISO 25010 to improve software quality. More info: https://fiqare.eu/

Swagger is provided for HTTP protocol in:
<server_host>:7896/api-docs

Note: npm install is needed

All test in Travis has been passed successfully and the coverage in Coveralls remains the same.

fgalan · 2019-12-16T19:04:34Z

package.json

    "mqtt": "3.0.0",
    "request": "2.88.0",
+    "swagger-jsdoc": "^3.4.0",
+    "swagger-ui-express": "^4.1.2",


Please use ~ instead of ^ for dependencies (have a look to other cases in this same file ;)

More things:

Swagger dependencies should be moved to devDependencies

The command to generate the swagger doc should be added to "scripts" section in this file, so any user running "npm run swagger" (or similar) may be able to generate it.

updated, Swagger dependencies moved to devDependencies with (~) instead of (^).

We don't have any command to generate the Swagger documentation, it is generated automatically. After npm update or install you could check it:
<server_host>:7896/api-docs

Thanks!

fixed in 3e1c1f9

We don't have any command to generate the Swagger documentation, it is generated automatically. After npm update or install you could check it:
<server_host>:7896/api-docs

The procedure to build and access to swagger documentation should be documented. For instance, with a small subsection within https://github.com/telefonicaid/iotagent-ul/blob/master/docs/usermanual.md#development-documentation

Btw, I have tried what you say:

$ npm update ... $ curl localhost:7896/api-docs curl: (7) Failed to connect to localhost port 7896: Conexión rehusada

so I understand the procedure is not exaclty that...

Hi @fgalan
I think that mistake is because the IoT Agent is not running. I'm sorry, I did not tell you that. You should run the IoT Agent (https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#usage) and then make the curl request.

fixed in 53b15a6

fgalan · 2019-12-19T12:22:10Z

docs/usermanual.md

+<server_host>:7896/api-docs
+```
+
+If you want to test the HTTP Protocol, two importants points:


From this point on, is this really needed to have the swagger web working at api-docs/ ? Or do you refer to steps needed to run IOTA-UL in general?

steps needed to run IOTA-UL in general

In that case, I'd suggest removing all this part (i.e. from L559). Note that you already include a link to a document that explains how to run IOTA in L553. Repeating a long explanation about it here is a bit out of scope from my point of view.

fixed in 2808c0b

jason-fox · 2019-12-21T11:00:49Z

docs/usermanual.md

+
+For example, you could use this script:
+
+```


Add bash code highlight

```bash

fixed in 8f66e1a

jason-fox · 2019-12-21T11:02:10Z

docs/usermanual.md


 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 
+by the protocol, in this case '/ul', just include apikey and deviceid (e.g: `/FF957A98/MydeviceId/cmd` and


Line 205 correct All topis => All topics
Line 207 replace '/ul' with backticks /ul to display as monospace

fixed in 8f66e1a

jason-fox · 2019-12-21T11:03:56Z

docs/usermanual.md

+If you want to test the HTTP Protocol, two importants points:
+
+-   you should know that other services are needed (see
+    https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#installation):


Remove URL from text - use a link e.g.

( see [installation](https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#installation) )

fixed in 8f66e1a

jason-fox · 2019-12-21T11:04:52Z

docs/usermanual.md

+    -   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)


Remove URL from text - use a link e.g.

[tutorial](https://fiware-tutorials.readthedocs.io/en/latest/iot-agent/index.html#connecting-iot-devices)

fixed in 8f66e1a

fiqare-secmotic · 2019-12-23T08:44:50Z

fixed in 8f66e1a

jason-fox · 2019-12-23T09:26:56Z

docs/usermanual.md

+### 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:


Missing square brackets for link:

[IoT Agent](http://etc.)

fixed in 29983d1

fiqare-secmotic · 2019-12-23T09:45:34Z

fixed in 29983d1

jason-fox · 2019-12-23T09:52:14Z

fixed in 29983d1

LGTM

jason-fox · 2019-12-23T09:52:42Z

fixed in 8f66e1a

LGTM

fgalan · 2020-01-07T20:07:36Z

At the present moment (January 7th, 2019), there are some comment threads (some from @jason-fox and some from e) not yet answered/fixed so I understand the work on this PR is ongoing.

@fiqare-secmotic , is my understanding correct?

fiqare-secmotic

Hi @fgalan We finished all the improvements but we commented "fixed in .." only in the end, sorry. I have updated the review. Is everything all right?

fgalan · 2020-01-08T15:18:02Z

docs/usermanual.md

+### 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


Suggested change

[IoT Agent](https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#usage) and then you can

IOT Agent (as explained [here](installationguide.md#usage) and then you can

fixed in 2808c0b

fgalan · 2020-01-08T15:19:22Z

lib/bindings/HTTPBindings.js

+        swaggerDefinition: {
+            info: {
+                title: 'IoT Agent UL2 - HTTP', // Title (required)
+                version: '1.0.0', // Version (required)


This refers to the version of the IOTA? In that case, it should be obtained from version field in package.json.

It is related to Swagger documentation version.

I think it would be a good idea to tie the version of the swagger documentation to the version of the IOTA Agent. It would be simpler.

The only case in which makes sense to have a version for the documentation and a version for the IOTA is the one in which the same IOTA version (from a code point of view) could have different documentation versions, which I think is not realistic.

The version of the swagger documentation has been changed to the same IOTA UL version how as requested but is important to know that this version really is the first documentation version.

fixed in 2164dc0

fgalan · 2020-01-08T15:22:59Z

docs/usermanual.md

+access to:
+
+```
+<server_host>:7896/api-docs


One doubt...

IOTA exposes two ports: one corresponding to the "southbound interface" (to which the devices send measures and command responses) and another corresponding to the "nourthbound interface" (in which the IOTA provides the provisioning API, i.e. to create a new device, etc.).

Does this /api-docs endpoint work in both ports? Or only in northbound/southbound?

we have developed the Swagger documentation only for the HTTP protocol (https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#http-binding), so this version of swagger documentation (1.0.0) works only in southbound.

Northbound is also HTTP-based...

However, if /api-docs only works in southbound, fine with it. I just want to confirm how it works ;)

Could you confirm?

This documentation has been based on the sending of measurements using exclusively the HTTP protocol, so works in southbound.

fixed in 2164dc0

fgalan · 2020-01-08T15:24:08Z

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


I'd suggest to add the following entry to CHANGES_NEXT_RELEASE:

- Add: /api-docs endpoint providing swagger-based documentation

or something similar

fixed in 2808c0b

jason-fox · 2020-01-20T20:42:37Z

lib/bindings/HTTPBindings.js

+            info: {
+                title: 'IoT Agent UL2 - HTTP', // Title (required)
+                version: '2.0.0', // Version (required)
+                description: 'This documentation explains the POST and GET requests to the route /iot/d' // Description (not required)


The Swagger spec states that the route is always /iot/d, however the config.js can be overridden by using a non-standard config or applying a Docker env variable. Maybe the description should use config.getConfig().iota.defaultResource to describe the route. It would be kind of tricky to alter the swagger definition itself.

fixed in 43ed851

fgalan · 2020-01-21T10:41:20Z

Please have a look to the travis CI report. Several linting errors appear:

lib/bindings/HTTPBindings.js: line 440, col 124, Line is too long.
lib/bindings/HTTPBindings.js: line 458, col 122, Line is too long.
lib/bindings/HTTPBindings.js: line 474, col 135, Line is too long.
lib/bindings/HTTPBindings.js: line 516, col 129, Line is too long.
lib/bindings/HTTPBindings.js: line 527, col 135, Line is too long.

fgalan · 2020-01-21T10:47:22Z

CHANGES_NEXT_RELEASE

@@ -1,2 +1,3 @@
 - Add: check response obj before use it handling http commands
 - Upgrade NodeJS version from 8.16.1 to 10.17.0 in Dockerfile due to Node 8 End-of-Life 
+- Add: /api-docs endpoint providing swagger-based documentation of the HTTP protocol


After clarifying that the swagger documentation refers only to southbound (https://github.com/telefonicaid/iotagent-ul/pull/412/files#r368682255), this line should be slightly modified:

Suggested change

- Add: /api-docs endpoint providing swagger-based documentation of the HTTP protocol

- Add: /api-docs endpoint providing swagger-based documentation of the HTTP southbound interface

fixed in 2c34c9a

fgalan · 2020-01-21T10:56:07Z

lib/bindings/HTTPBindings.js

+        swaggerDefinition: {
+            info: {
+                title: 'IoT Agent UL2 - HTTP', // Title (required)
+                version: '2.0.0', // Version (required)


I see you changed version 1.0.0 to 2.0.0 in commit 2164dc0. However, this is not the inteded fix.

I think it would be a good idea to tie the version of the swagger documentation to the version of the IOTA Agent. It would be simpler.

The IOTA Agent version is taken from packages.json. Thus the solution should be something like:

var package = require('../../package.json'); ... info: { ... version: package.version, }

fixed in 2c34c9a

fgalan · 2020-01-21T11:01:49Z

docs/usermanual.md

+
+In order to run Swagger, you need to execute the IOT Agent (as explained [here](installationguide.md#usage) and then you
+can access to:
+


I'd suggest to add a sentence about which API is being covered by the swagger documentation. Something like this:

The swagger documentation provided at /api-docs covers the HTTP southbound interface of the agent. The northbound HTTP interface is not covered.

fixed in 2c34c9a

fgalan · 2020-01-23T09:54:51Z

docs/usermanual.md

+
+### Swagger
+
+In order to run Swagger, you need to execute the IOT Agent (as explained [here](installationguide.md#usage) and then you


Travis CI detects the following problem regarding this line:

551:49 ✓ error Incorrect usage of the term: “IOT”, use “IoT” instead terminology

Please, fix it.

(Full log: https://travis-ci.org/telefonicaid/iotagent-ul/jobs/639955851?utm_medium=notification&utm_source=github_status)

fixed in 8345090

fgalan

LGTM (at commit 8345090). Thanks for your contribution!

In order to keep the homogeneity along with all the IOTA suite, we will wait to merge this PR until a similar PR providing swagger documentation could be done in the following repositories:

IOTA Lib, covering the northbound interface with a swagger specification
IOTA JSON, covering the HTTP southbound interface with a swagger specificaction

Not sure about:

ITOA LWM2M. As far as I understand, Sigfox protocol is not HTTP based. Can swagger be used to describe a non-HTTP based protocol?
IOTA Sigfox. Can swagger be used to describe a CoAP based (as LWM2M is, as far as I know) protocol?

fgalan · 2020-07-03T11:58:06Z

After merging PR #415 I'm afraid some merging conflict have arisen in this PR. Fortunatelly, the solution seems easy, detailed by @jason-fox at telefonicaid/iotagent-manager#171 (comment)

all you need to do is merge and accept yours

Thereafter
npm i
npm run lint
And fix any es6 errors raised. (Alternatively you could disable the failed rule for your files if necessary)

Sorry for the incoveniences

fiqare-secmotic · 2020-07-07T09:02:56Z

thanks for the info! @fgalan

Documentation Swagger

c0fa899

fgalan reviewed Dec 16, 2019

View reviewed changes

Documentation Swagger (improved)

3e1c1f9

fgalan mentioned this pull request Dec 17, 2019

Secmotic fiQare PR #407

Closed

user manual with swagger

53b15a6

fgalan reviewed Dec 19, 2019

View reviewed changes

jason-fox reviewed Dec 21, 2019

View reviewed changes

user manual improved

8f66e1a

jason-fox reviewed Dec 23, 2019

View reviewed changes

user manual (link IoT Agente) improved

29983d1

fiqare-secmotic commented Jan 8, 2020

View reviewed changes

fgalan mentioned this pull request Jan 8, 2020

Fiqare perseo-core improvements telefonicaid/perseo-core#151

Merged

fgalan reviewed Jan 8, 2020

View reviewed changes

User Manual updated

2808c0b

fgalan mentioned this pull request Jan 14, 2020

Fiqare perseo-fe improvements telefonicaid/perseo-fe#419

Merged

Swagger documentation version changed

2164dc0

jason-fox reviewed Jan 20, 2020

View reviewed changes

Swagger documentation description modified

43ed851

fgalan reviewed Jan 21, 2020

View reviewed changes

fiqare-secmotic added 3 commits January 21, 2020 14:22

new improvemet for Swagger documentation

2c34c9a

change branch to fiqare-secmotic-swagger for travis

f6a68ee

updated to previous version

68b791f

fgalan reviewed Jan 23, 2020

View reviewed changes

term IoT fixed

8345090

fgalan approved these changes Jan 24, 2020

View reviewed changes

jason-fox mentioned this pull request Jun 22, 2020

Should every IoT Agent align to use eslint telefonicaid/iotagent-node-lib#830

Closed

	[IoT Agent](https://github.com/telefonicaid/iotagent-ul/blob/master/docs/installationguide.md#usage) and then you can
	IOT Agent (as explained [here](installationguide.md#usage) and then you can

		@@ -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

	- Add: /api-docs endpoint providing swagger-based documentation of the HTTP protocol
	- Add: /api-docs endpoint providing swagger-based documentation of the HTTP southbound interface


		In order to run Swagger, you need to execute the IOT Agent (as explained [here](installationguide.md#usage) and then you
		can access to:


		### Swagger

		In order to run Swagger, you need to execute the IOT Agent (as explained [here](installationguide.md#usage) and then you

Conversation

fiqare-secmotic commented Dec 16, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fiqare-secmotic Dec 17, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fiqare-secmotic commented Dec 23, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fiqare-secmotic Jan 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fiqare-secmotic commented Dec 23, 2019

Uh oh!

jason-fox commented Dec 23, 2019

Uh oh!

jason-fox commented Dec 23, 2019

Uh oh!

fgalan commented Jan 7, 2020

Uh oh!

fiqare-secmotic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fiqare-secmotic Dec 17, 2019 •

edited

Loading

fiqare-secmotic Jan 8, 2020 •

edited

Loading

fgalan Jan 9, 2020 •

edited

Loading

fgalan Jan 8, 2020 •

edited

Loading