Introduction

OCaml-Swagger is a code generator that implements
Swagger 2.0
API clients in OCaml.

The motivation for this project was the development of a
Kubernetes API
client, which can be found in the
Kubecaml
project.

Therefore, while the Kubernetes API is quite large and uses many of Swagger's
features, this library doesn't currently support all of them. Remaining features
will be implemented if needed to support the Kubernetes API, though of course
contributions are welcome.

Installation

OCaml-Swagger is available on opam:

$ opam install swagger

Usage

Most users will probably only need to use the Swagger.codegen function to
parse an API specification and generate the OCaml code:

let () =
  Swagger.codegen
    ~input:Sys.argv.(1)
    ~output:stdout
    ~path_base:"/"
    ~definition_base:"io.k8s."
    ~reference_base:"#/definitions/io.k8s."
    ~reference_root:"Definitions"

This call instructs OCaml-Swagger to read the API specification from the file
name given in the first command-line argument and output the resulting code to
the standard output.

The remaining arguments are prefixes that are stripped from the API definitions
when generating module names. For example, in the Kubernetes API, the
Definitions Objects
are named using a reverse-domain name convention, as in
io.k8s.api.apps.v1.DaemonSet. Given the definition_base above, the
corresponding OCaml module would be Api.Apps.V1.Daemon_set, that is, the
io.k8s prefix is ignored in the OCaml module structure.

Similarly, references to definitions are specified in the Kubernetes API as
"$ref": "#/definitions/io.k8s.api.apps.v1.DaemonSet". The reference_base
parameter allows a prefix to be ignored in
Reference Objects.

Finally, the reference_root parameter specifies the submodule in which the
code for Definition Objects will be created.

The generated code

Since Swagger APIs may contain reference cycles, OCaml-Swagger uses the
recursive modules trick
to work around the OCaml restriction that forces one to only reference types or
values that have been previously defined. The wrapper recursive module that
acts as a namespace will have its named derived from the API's
Info Object's
title field.

Inside this module, a module structure mirroring the URI structure of
definitions and operations defined in the Swagger specification will be created.

The code for Definitions defines a type t for the definition, a create
function taking as many arguments as necessary to create it, and one accessor
function for each definition property.

Operation modules have one function per HTTP operation defined in the API
specification, named after the HTTP verb, in lowercase (i.e., get, put,
post, delete, patch and options), each taking a number of parameters
according to the operations' definition. Operations also take an extra
parameter, an Uri.t (from OCaml-URI),
used to connect to the API server. In principle, this URI should only contain
the host and port of the API server, as path and query string parameters will
be appended automatically as needed by the operation functions themselves.

With regard to path templating (i.e. replaceable sections of an URL marked with
a path variable name inside curly braces), OCaml-Swagger will create a submodule
in the form By_{variable_name} for the templated path. To give a concrete
example, the path template /api/v1/namespaces/{name}, present in the
Kubernetes API, will create a module structure such as below.

...
module Namespaces = struct
  ...
  module By_name = struct
    let get ~name ... =
      ...
  end
  ...
end
...

Finally, OCaml-Swagger tries to define modules and functions using OCamlish
name conventions. Namely, modules are defined in Capitalized_snake_case style
and functions in lower_snake_case style, whenever possible.