Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[OCaml] new client generator #3446

Merged
merged 40 commits into from Jul 28, 2019

Conversation

@cgensoul
Copy link
Contributor

commented Jul 24, 2019

#1159 Add OCaml client code generation support

This PR answers #1159 and adds OCaml Client code generation to openapi-generator. The generated OCaml project relies on the dune tool for the build process and uses :

  • cohttp as the http client lib using the lwt_unix backend (lwt is a future lib for OCaml, a competing future lib is Async which Cohttp supports as well but this generator only target the lwt implementation for now)
  • yojson as the JSon serialization lib
  • ppx_deriving_yojson for automatic generation of JSon serializers and deserializers for generated types
  • ppx_deriving.std for automatic generation of string convertion functions for generated types

It supports headers params, path params, query params, form params and body params. It currently has no support for authentication, nor file upload.

It generates one model file per OAS definition except for OAS enum definitions for which no model file is generated. Enums are treated globally and are all generated in a enums.ml file that contains one type per distinct enumeration present in the input file, even for enumerations that are not proper definitions but just local restrictions on a string parameter of an operation.

Note that generating one model file per OAS definition will work as long as there are no mutually recursive OAS definitions in the input file. Otherwise the generated OCaml code will not compile since it will generate mutually recursive compilation units which is not supported by the language.

For APIs files, both an implementation (.ml) and an interface (.mli) files are generated.

Christophe Gensoul and others added some commits Jul 12, 2019

Christophe Gensoul
Avancée dans la gestion des enums : reste à traiter le fait que Yojso…
…n sérialize les variants comme des tableaux JSON.
Prise en compte du fait que Yojson représente les variants constants …
…sous forme d'un tableau JSON contenant une unique string.
Christophe Gensoul
Utilisation des variants polymorphe pour les enums car il se peut que…
… plusieurs énumérations partagent des valeurs communes ce que ne permettent pas les variants ordinaires au sein d'un même module.
Christophe Gensoul
Avancées dans le générateur de code OCaml : le code produit compile e…
…t prendre en compte les pathParams, les queryParams, les headersParams, les bodyParams et la réponse JSON. Manque le support du multipart, du form encoded et des mécanismes d'authentification.
Christophe Gensoul
Correction de problèmes dans la génération mis en évidence par l'util…
…isation d'un fichier OAS plus gros et complexe que Petstore.
Christophe Gensoul
Mapping du case Error de Ppx_deriving_yojson_runtime.ok_error vers l'…
…exception Failure pour avoir des types plus simples et non dépendants de Pppx_deriving_yoson_runtime dans les APIs générées.
Christophe Gensoul
Make modules/openapi-generator/src/test/resources/3_0/petstore-with-f…
…ake-endpoints-models-for-testing.yaml generate properly.
Christophe Gensoul
Added generated code for modules/openapi-generator/src/test/resources…
…/3_0/petstore-with-fake-endpoints-models-for-testing.yaml.
Christophe Gensoul
Better handling of enums and map container and better sanitizing of g…
…enerated identifiers to support all the corner cases present in modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml.
Christophe Gensoul
Collect enum schemas in items properties of operation parameters in t…
…he case of ArraySchema parameters. This allows correct processing of modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml.
Collect enums also in additional properties schemas of operation para…
…meters in the case of MapSchema parameters (if this type of parameter can is allowed).
@@ -0,0 +1,703 @@
/*
* Copyright 2018 OpenAPI-Generator Contributors (https://openapi-generator.tech)
* Copyright 2018 SmartBear Software
@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 25, 2019

Finally it was so easy to fix that I did it anyway ;)

Christophe Gensoul added some commits Jul 25, 2019

@wing328

This comment has been minimized.

Copy link
Member

commented Jul 26, 2019

@cgensoul 👍 so is it ready for review and merge into master?

@wing328

This comment has been minimized.

Copy link
Member

commented Jul 26, 2019

Are there some commands to make sure the OCaml Petstore sample compiles?

An auto-generated README would be nice so that OCaml beginners will find it easy to use the OCaml library.

Added [@default] on enum record fields for which the enum type has on…
…ly one accepted value so that those fields can be deserialized even if the value is absent of the json payload.
@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 26, 2019

The command to compile the lib once all the tools (opam first then dune through opam is the easiest path) and dependencies (through opam as well) are installed is :

dune build

at the root of the generated code directory.

I'll add a README pointing to installation instructions of the tools and dependencies next week. There is an example program using the library committed in the repository in the samples/client/petstore/ocaml-client/bin directory. It's called test.ml and has an accompanying dune build file. I'll clean it up and reference it in the README.

Regarding merging to master, it can be merged without any risk since it's all new code and no existing classes have been modified by this PR but I think proper handling of response codes should be added before it's really useful to anyone. So maybe it's best to wait a bit to save some reviewing work ?

@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2019

I added handling of response codes ;)

@wing328

This comment has been minimized.

Copy link
Member

commented Jul 28, 2019

Tried running dune build locally and I got:

➜  ocaml-client git:(cgensoul-ocaml-client) dune build


File "dune", line 6, characters 18-33:
6 |    (libraries str cohttp-lwt-unix lwt yojson ppx_deriving_yojson.runtime)
                      ^^^^^^^^^^^^^^^
Error: Library "cohttp-lwt-unix" not found.
Hint: try: dune external-lib-deps --missing @@default
File "dune", line 7, characters 20-39:
7 |    (preprocess (pps ppx_deriving_yojson ppx_deriving.std))
                        ^^^^^^^^^^^^^^^^^^^
Error: Library "ppx_deriving_yojson" not found.
Hint: try: dune external-lib-deps --missing @@default

Do I need to run other commands in order to install those libraries locally?

@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 28, 2019

@wing328

This comment has been minimized.

Copy link
Member

commented Jul 28, 2019

Thanks for the tips. It works for me after I run opam install ppx_deriving_yojson cohttp ppx_deriving cohttp-lwt-unix (wihtout .std)

I would recommend including the opam install command in the readme as well.

@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 28, 2019

@wing328 wing328 changed the title Ocaml client [OCaml] new client generator Jul 28, 2019

@wing328 wing328 merged commit 1713c76 into OpenAPITools:master Jul 28, 2019

4 checks passed

Shippable Run 9411 status is SUCCESS.
Details
ci/circleci Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@wing328

This comment has been minimized.

Copy link
Member

commented Jul 28, 2019

@cgensoul thanks for the new generator. Do you have a Twitter account so that I can tag you in my tweet to promote the new generator?

@cgensoul

This comment has been minimized.

Copy link
Contributor Author

commented Jul 28, 2019

@wing328

This comment has been minimized.

Copy link
Member

commented Jul 28, 2019

I've filed #3483 for various enhancements.

smasala added a commit to smasala/openapi-generator that referenced this pull request Aug 1, 2019

[OCaml] new client generator (OpenAPITools#3446)
* Début d'un générateur pour OCaml.

* Ajout du script bash de generation pour OCaml.

* Implémentation de la partie model du générateur OCaml.

* Suppression du fichier Model.mustache.

* Légère modification dans le générateur OCaml.

* Début d'implémentation de la génération des opérations.

* Avancées dans l'implémenatation des opérations.

* Avancée dans la gestion des enums : reste à traiter le fait que Yojson sérialize les variants comme des tableaux JSON.

* Prise en compte du fait que Yojson représente les variants constants sous forme d'un tableau JSON contenant une unique string.

* Utilisation des variants polymorphe pour les enums car il se peut que plusieurs énumérations partagent des valeurs communes ce que ne permettent pas les variants ordinaires au sein d'un même module.

* Avancées dans le générateur de code OCaml : le code produit compile et prendre en compte les pathParams, les queryParams, les headersParams, les bodyParams et la réponse JSON. Manque le support du multipart, du form encoded et des mécanismes d'authentification.

* More tests.

* Correction de problèmes dans la génération mis en évidence par l'utilisation d'un fichier OAS plus gros et complexe que Petstore.

* Mapping du case Error de Ppx_deriving_yojson_runtime.ok_error vers l'exception Failure pour avoir des types plus simples et non dépendants de Pppx_deriving_yoson_runtime dans les APIs générées.

* Ajout de la génération des fichiers d'interfaces .mli pour les APIs.

* Ajout du support des parametres de type x-www-form-urlencoded.

* Le paramètres d'url de type number étaient mal gérés.

* Cleanup.

* Replace block comment start and end sequences in input text.

* Make apis calls without a return type return unit rather than Yojson.Safe.t.

* Make modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml generate properly.

* Added generated code for modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml.

* Better handling of enums and map container and better sanitizing of generated identifiers to support all the corner cases present in modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml.

* Correcting a violation : using toLowerCase without relying on the default Locale.

* Changed authoring in partial_header.mustache.

* Deleted commented code.

* Collect enum schemas in items properties of operation parameters in the case of ArraySchema parameters. This allows correct processing of modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml.

* Collect enums also in additional properties schemas of operation parameters in the case of MapSchema parameters (if this type of parameter can is allowed).

* Removed copy-pasted Copyright notice from SmartBear.

* update doc

* Use Locale.ROOT instead of Locale.ENGLISH for toLowerCase calls.

* Make GET operations with body generate compilable code.

* Updated ocaml-client generated samples using the latest version of the OCaml code generator.

* Added [@default None] for record fields with option types so that if those fields are missing at deserialization time, None is assumed.

* Added support of api keys in query params.

* Updated generated ocaml samples to reflect latest changes in templates.

* Added [@default] on enum record fields for which the enum type has only one accepted value so that those fields can be deserialized even if the value is absent of the json payload.

* Delete useless space character in template.

* Added proper handling of http response codes.

* Updated generated ocaml samples to reflect latest changes in templates.
@wing328

This comment has been minimized.

Copy link
Member

commented Aug 6, 2019

Note

This generator is still in beta and may subject to breaking changes (without fallbacks) in the future.

@wing328

This comment has been minimized.

Copy link
Member

commented Aug 10, 2019

@cgensoul thanks for the PR, which has been included in the 4.1.0 release: https://twitter.com/oas_generator/status/1160000504455319553

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.