Created by: f-f
PR checklist
-
Read the contribution guidelines. -
Ran the shell script under ./bin/
to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.sh
and./bin/security/{LANG}-petstore.sh
if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\
. -
Filed the PR against the correct branch: Default: master
. -
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.
Description of the PR
This big PR adds support for generating Clojure Specs from OpenAPI Models. Spec is a core library available since Clojure 1.9. Description from the linked page:
The
spec
library specifies the structure of data, validates or destructures it, and can generate data based on the spec.
Things going on in this PR:
-
Update of the Clojure version
1.7.0
->1.9.0
: This is backwards compatible, so users can just bump their version and everything should be fine. -
Generate
spec
files from Models: they are in thespecs/
folder, and imported by allapi
files. This is done with the Data Specs from thespec-tools
library, as they are much nicer to read/write than vanilla specs. -
Add types to
api
functions viadefn-spec
: in this way at development time all the inputs and outputs of function calls will be checked and will except if they don't conform (you need to callorchestra.spec.test/instrument
for it to be active). - Add conforming of data returned from the API to the proper model/spec: this includes e.g. creating date objects instead of getting back strings.
-
Add
:decode-models
setting inapi-context
: so the above conforming can be turned off if it's indesiderable. This is opt-out (but we can make it opt-in if we want to keep backwards compatibility).
I am not entirely sure this is correct in all cases (e.g. I'm suspicious about multiple arities), but we have an API much bigger than Petstore on which this is already deployed, and the generated code looks fine and works.
/cc @wing328 @xhh
Moreover, if this PR goes in I'd be available to be in the Clojure generator "technical committee", as the list is currently empty, and I could help with it.