search

joffrey-bion / livedoc

A not-so-annotation-based documentation generator for REST and websocket services
MIT License
4 stars 2 forks source link

Version the API spec independently from the library #120

Closed joffrey-bion closed 6 years ago

joffrey-bion commented 6 years ago

Currently it's frustrating not to be able to use an old JSON with a new version of livedoc even if the API didn't change. It'd be nice to version the spec file independently from the library so that it's actually possible.

ST-DDT commented 6 years ago

I usually use data-artifacts that follow a different versioning schema/schedule to accomplish that. That way I am sure that no incompatibility sneaks in. Which method did you consider using?

As an alternative the GUI could provide a button to "try anyway".

joffrey-bion commented 6 years ago

What do you mean by data artifact? I have never heard of that.

I was thinking about generating some sort of schema from the model files of the Livedoc class and children. Taking the hash of the schema, I could check for changes and upgrade the version automatically when the hash changes. But for starters, just a manual increment would already be an improvement, but it's subject to human errors.

Otherwise, yes, the UI could provide some sort of mechanism to allow forcing.

ST-DDT commented 6 years ago

The data artifact is just another jar file that only contains the data classes/schema you would return in a controller.

Since the data artifact does not have any other dependencies (except for annotations) it cannot reference anything that it does not contain itself, thus it is the only thing that determines the UI/backend compatibility. That way you have a fixed data version (= jar version). For the versioning schema you can something like semver.

The data-artifact does not contain any controllers or logic. It is independent from Spring and other frameworks. (it might contain annotations for compatibility/serialization though). Theoretically that artifact and a json serializer is all you need to test the frontend.

Shinigami92 commented 6 years ago

In my opinion, this ticket needs a badge 'Prio: high'

We have several backends and a hosted docker container Livedoc-Ui. There are already outdated jsondoc backends because we can not update every backend at once with a new livedoc version

joffrey-bion commented 6 years ago

Understood, I'll do my best to work on it soon, but my free evenings are unfortunately scarce. I first need to finish the overridable IDs feature, so that problems like https://github.com/joffrey-bion/livedoc/issues/118 and https://github.com/joffrey-bion/livedoc/issues/122 can be worked around while waiting for a proper fix.