search

SignalK / specification

Signal K is a JSON-based format for storing and sharing marine data from different sources (e.g. nmea 0183, 2000, seatalk, etc)
Other
91 stars 68 forks source link

[WIP] Create openapi definitions for REST API's #514

Closed rob42 closed 5 years ago

rob42 commented 5 years ago

Goal: To have a well defined definition of the signalk REST API's in a standard format to ease development and testing of implementations. See https://www.openapis.org

Details: Created an initial openapi 3 definition that describes the Signalk API's, The definitions are very much a first cut, and there are many changes required as some of the interfaces are currently still WIP and therefore hard to define, but a commit was required to create the pull request :-)

This document was auto-generated from the Artemis server, using swagger 3 annotations to the Apache jersey implementation. See https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations.

When signalk-java (Artemis branch) is installed the swagger-ui can be viewed (and tried) against the Artemis server at http://localhost:8080/docs/index.html.

rob42 commented 5 years ago

The api can also be viewed (but 'try it' will fail) at https://petstore.swagger.io/

You need to post the openapi.json url here on github into the Explore field, eg https://raw.githubusercontent.com/SignalK/specification/9a34aeb77fb8c2464e884a229407180677a23c45/swagger/openapi.json

The url will probably change with further commits here. Click on the latest commit, veiw full file, select 'raw', copy the url.

tkurki commented 5 years ago

Would pruning this to include just the apis already in the spec be the next step? Then we can get that into master and start building on it.

rob42 commented 5 years ago

Pruned and some improvements to definitions. Authentication API should be correct now. Others are still a work in progress. Reviews welcome.

The api can also be viewed (but 'try it' will fail) at https://petstore.swagger.io/

You need to post the openapi.json url here on github into the Explore field, eg https://raw.githubusercontent.com/SignalK/specification/dc5dac794a50133df5a9a0ebfe63c8f461d88c2a/swagger/openapi.json

tkurki commented 5 years ago

@rob42 I don't think this was ready for merging. Historically we have been imho too eager to add stuff to the spec when things have not been quite in the shape they should be. This results in inconsistencies: for example now you have added /signalk/v1/history/ to the specification, obly mentioned in one json document. There is no clear definition of what the role of the openapi.json doc is and where and how it should or could be used.

I would not have merged this. In my opinion specification master is not in a publishable condition now. If we want to stick to maintaining backwards compatibility removing stuff from the spec is not trivial and deprecation mechanism is not free of effort either.

rob42 commented 5 years ago

It got dragged in by #536 . Reverted now.