API Documentation

[AntoineDao]

Step 0:

• [x] I've read the contribution guidelines!

Expected Behaviour

Updates in the server REST API spec should automatically generate API docs from said spec.

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]

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]

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

[AntoineDao]

Meant to comment not close. My bad!!

[didimitrie]

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]

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