search

GALAglobal / TAPICC-API-implementation

TAPICC API implementation using node.js framework sails.js
Other
6 stars 1 forks source link

decoupling swagger file from the implementation #38

Closed Alino closed 6 years ago

Alino commented 6 years ago

Feedback from Jeroen:

I have the strong impression that the current design of the API is heavily influenced by what the sails framework generates for you. That is not a good way to design an API since design and implementation choices made by the framework will likely leak into the design of the API. This is normally fine if you are using the framework to generate a backend for your own application, but in this case you are working on an API that has a very broad scope and needs to be implemented on a wide variety of platforms by a wide variety of vendors. In such cases I would go around this the other way: I would create a swagger file that defines the API and then use the framework to implement the API. Because the sails framework can generate a swagger file as well, you can (partially) verify the correctness of the implementation by comparing the two swagger files.

Alino commented 6 years ago

The design of the API routes and data models was initially created as a mind map by me and Jim. Then I put those data models into the sails implementation and created the routes. There is a module for sails.js which I have forked and modified to fit our needs to generate the swagger spec automatically for us. This really helped us to kickstart creating the swagger spec. The swagger spec. is not perfect yet, and I would say, it is still under the design process. Many things were not decided yet, and there are github issues for that which need discussions and decision making. But I can see your point, that the swagger spec is under the influence of the module which I maintain. This could be also difficult for other people to collaborate if they wanted to make changes to the swagger spec. So I agree with you, that we can have one swagger file somewhere, which would be touched manually, and the implementation would be trying to match that spec. I think that this is now more achievable than before, since we have now a good start with the spec.

Alino commented 6 years ago

Maybe we should put the swagger definition to swagger hub platform and collaborate there? I have recently watched this video - Collaborating Across the API Lifecycle: How to Setup an API Workflow that Scales

Alino commented 6 years ago

I have played a little bit with the swagger file on the swagger hub, I have reordered the routes and reorganised the tags, deleted few duplicates and fixed validation errors and warnings.

https://app.swaggerhub.com/apis/Alino/tapicc-api/0.0.3

Please know that the swagger hub cannot talk to your localhost (it is proxying it to their server), if you wanna try the routes with your local implementation, you should use standalone Swagger UI and load the swagger file there. http://localhost:1337/docs/?url=https://api.swaggerhub.com/apis/Alino/tapicc-api/0.0.3

(maybe next step should be to make the route /docs automatically open the latest swagger definition on swagger hub, without the need to put the url there manually)

Alino commented 6 years ago

Ok the integration between swaggerHub and github is done, it's syncing the swagger file here https://github.com/GALAglobal/TAPICC-API-implementation/tree/master/assets/swaggerhub and Swagger UI has been updated to load the file from that path automatically.