Open API spec files

[kyyberi]

The repository is logical place to look for Open API spec (yaml) files for all the FIWARE standardized APIs. Yet there's currently none. If the files are not collected here, then at least add to readme where the files are.

[fgalan]

They are in the gh-pages branch (https://github.com/Fiware/specifications/tree/gh-pages) which maps with the automatic web server provided by github.io, e.g: http://fiware.github.io/specifications/ngsiv2/stable/

You are right: the README.md at master branch should explain that.

[kyyberi]

Thank you for answer and more information. I looked at the sources and I only find API Blueprint references:

var embed = new Apiary.Embed({
      apiBlueprint: "FORMAT: 1A\nHOST: http://orion.lab.fiware.org\nTITLE: FIWARE-NGSI v2 

I was expecting to find spec files in Open API format, https://github.com/OAI/OpenAPI-Specification

[juliozinga]

A simple question. Where is the source of this content: http://fiware.github.io/specifications/ngsiv2/stable/ ? I suggest you have examples for python3. And I would like to contribute to these examples.

[fgalan]

Sources are here in .apib format:

https://github.com/telefonicaid/fiware-orion/tree/master/doc/apiary/v2

However, the stable documents shoudn't be touched, as they correspond to "frozen" RC versions of the NGSIv2 API. If you plan to contribute focus on the following ones:

• fiware-ngsiv2-reference.apib (which maps to http://fiware.github.io/specifications/ngsiv2/latest/)
• fiware-ngsiv2-cookbook.apib (which maps to http://fiware.github.io/specifications/ngsiv2/latest/cookbook/)

Typically, the second one (cookbook) was aimed at examples. However, it has not been touched (last time 2 years ago ;). Thus, probably it is obsolete and it would be a good contribution to review it, update it and expand it. Maybe @jmcanterafonseca have some feedback regarding this.

Regarding Python3, note that .apib are agnostic with regards with programming language. Thus, I'm not sure that is a good place for such examples.

[jmcanterafonseca]

We are going to migrate progressively to the Swagger Open API Format with the help of tools like https://apimatic.io/transformer

Open API Specifications will be hosted by this repository

We will start with NGSIv2 specification and IDAS specification. Then owner of other GEs will be asked to perform their migration

[fgalan]

Open API Specifications will be hosted by this repository

You mean the HTML render of the specification? Or the source (i.e. .apib equivalent in the swagger world)?

[jmcanterafonseca]

First version of the NGSIv2 specification in Open API Format can be found at

http://fiware.github.io/specifications/OpenAPI/ngsiv2/ngsiv2-openapi.json

Please note that further tweakings might be needed and contributions from the Community at that respect are welcome

[fgalan]

How do you ensure that the ngsiv2-openspai.json keeps synced with current .apib? The risk of forking (i.e. modifications in some place not applied to the other) is high... Source should be only one, the others be automatic derivations.

[jmcanterafonseca]

@fgalan there is no longer rendering of Swagger specs as Swagger provides a Swagger UI viewer. We will deploy an instance of the viewer on the FIWARE Lab so anyone can easily browse the Swagger specs.

Idea is to have swagger.lab.fiware.org for this purpose.

[jason-fox]

Following on from @jmcanterafonseca - a forwarding to the Swagger UI viewer at https://swagger.lab.fiware.org/ is now in place - http://fiware.github.io/specifications/OpenAPI/ngsiv2 (without the JSON file name) will display the latest raw Swagger file from master.

I have updated the README on both gh-pages and master to add visible links to the specs.

[fgalan]

I have one doubt:

Looking to http://fiware.github.io/specifications/OpenAPI/ngsiv2 how do you ensure that a change in https://github.com/telefonicaid/fiware-orion/blob/master/doc/apiary/v2/fiware-ngsiv2-reference.apib (the source of the NGSIv2 specification) is propagated to that web page? For instance, if a new method is defined or a new parameter added to an existing method.

(In fact, is the same concern expressed at https://github.com/Fiware/specifications/issues/1#issuecomment-357901513 but reformulated in a diferent way :)

[jason-fox]

Currently a change in fiware-ngsiv2-reference.apib calls a sync function to update the swagger file on master https://raw.githubusercontent.com/Fiware/specifications/master/OpenAPI/ngsiv2/ngsiv2-openapi.json which is created by an apiamatic translation (Apiary to Swagger). Currently, the same file is also copied to the gh-pages branch.

This means that:

1. The master branch of specifications contains only Swagger files e.g

• on master - ../OpenAPI/ngsiv2/ngsiv2-openapi.json will be the latest generated swagger file.

2. The gh-pages branch of specifications contains HTML and other assets

• on gh-pages - ../ngsiv2/index.html holds the generated Apiary documentation
• on gh-pages - ../OpenAPI/ngsiv2/index.html is a forwarding file (which references the specification file on the master branch) and will always display a swagger UI for the latest generated swagger file.
• on gh-pages - ../OpenAPI/ngsiv2/ngsiv2-openapi.json will be a copy of the latest generated swagger file.

I'm not entirely sure if it is necessary to maintain the gh-pages copy of the swagger file - i.e. the link http://fiware.github.io/specifications/OpenAPI/ngsiv2/ngsiv2-openapi.json as a direct JSON representation of the spec but it works as a URL shortener. If this duplicate copy is not needed then the the JSON representations on gh-pages should be deleted to avoid confusion.

[jmcanterafonseca]

@jason-fox if we properly configure this repo gh-pages can be removed

@caa06d9c could you take care of reconfiguring and testing everything?

[caa06d9c]

ok