search

speckleworks / SpeckleServer

Check a brand new Speckle at: https://github.com/specklesystems
http://speckle.systems
MIT License
110 stars 29 forks source link

API Documentation #133

Open AntoineDao opened 5 years ago

AntoineDao commented 5 years ago

Step 0:

Actual Behaviour

API docs are generated manually.

Affected Projects

Most of the clients I guess could benefit from this. We could potentially even generate all clients from the generated API spec. Even if we can't generate the clients, it will be a lot easier to create and maintain them as well as keep them homogenous across different languages.

Proposed Solution (if any)

I've got a twofold solution proposal: one for API object schemas and the other for REST endpoint documentation:

  1. Object Schemas: use jsonschema to validate objects sent to and from the API. If schemas are set somewhere on the server's code base then it will be relatively easy to implement schema validators on all the clients also by either copying it over or even (if we want to be super fancy) providing server calls to the different schemas so clients receive schemas directly from the live server.
  2. REST Endpoint doc: use swagger-jsdoc (nice example implementation here) to generate swagger.json and use swagger-ui to render it from the server (so each server whatever version it is contains it's own in-built documentation).
didimitrie commented 5 years ago

I've finally gotten time to read this through. I'm super happy with (2), and by all means it should happen.

Re point (1), i wouldn't rush into it yet, as that's a bigger issue relating to how speckle kits work and how they will integrate with the server (in a 2.x.x iteration of speckle...)

AntoineDao commented 5 years ago

Cool cool cool. Have I got mandate to break everything then? :smile:

AntoineDao commented 5 years ago

Meant to comment not close. My bad!!

didimitrie commented 5 years ago

once this PR (https://github.com/speckleworks/SpeckleServer/pull/149) is in master and out to maintainers, we can look at adding copy-pasting all the swagger jsdocs and ci-ing the api specs an' all. @logan12358 split the original specs and made them magically compile docs, so i'll rope him in on this convo.

AntoineDao commented 5 years ago

I'll start a PR to get the docs generated. We can then figure out how to dump them into the existing doc setup.