Skip to content
GitLab

[Clojure] Add model generation and conforming

Merged Administrator requested to merge github/fork/f-f/clojure/add-model-generation into 4.0.x

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 the specs/ folder, and imported by all api files. This is done with the Data Specs from the spec-tools library, as they are much nicer to read/write than vanilla specs.
  • Add types to api functions via defn-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 call orchestra.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 in api-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.