package swagger

OCaml-Swagger

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.