anil.recoil.org
OpenAPI generator for OCaml with Requests/Eio/Jsont
metadata
-70
CLAUDE.md
-70
CLAUDE.md
···
1
-
# OCaml OpenAPI
2
-
3
-
OpenAPI code generator for OCaml, specialized for:
4
-
- **requests** HTTP library (Eio-based)
5
-
- **jsont** for JSON codecs
6
-
- Stdlib-first approach (avoiding Base/Core)
7
-
- OCamldoc comments from OpenAPI descriptions
8
-
9
-
## Quick Start
10
-
11
-
```bash
12
-
# Generate client from OpenAPI spec
13
-
opam exec -- dune exec -- openapi-gen generate spec.json -o ./generated -n my_api
14
-
15
-
# Include dune regeneration rules
16
-
opam exec -- dune exec -- openapi-gen generate spec.json -o ./generated -n my_api --regen
17
-
```
18
-
19
-
## Generated Code Structure
20
-
21
-
```
22
-
output/
23
-
├── dune # Build configuration (wrapped library)
24
-
├── dune.inc # Regeneration rules (if --regen used)
25
-
├── types.ml # Type definitions with jsont codecs
26
-
├── types.mli # Type interfaces
27
-
├── client.ml # API client functions using requests
28
-
├── client.mli # Client interface
29
-
├── <api_name>.ml # Wrapped main module
30
-
└── <api_name>.mli # Main module interface
31
-
```
32
-
33
-
## Usage
34
-
35
-
After generation, you can use the API like:
36
-
37
-
```ocaml
38
-
(* Access types through the wrapped module *)
39
-
let album : Immich.Types.AlbumResponseDto.t = ...
40
-
41
-
(* Create a client and make requests *)
42
-
Eio_main.run @@ fun env ->
43
-
Eio.Switch.run @@ fun sw ->
44
-
let client = Immich.Client.create ~sw env ~base_url:"http://localhost:2283/api" in
45
-
let json = Immich.Client.get_activities ~album_id:"..." client () in
46
-
...
47
-
```
48
-
49
-
## Regeneration with Dune
50
-
51
-
When using `--regen`, the generated `dune.inc` contains rules for:
52
-
53
-
```bash
54
-
# Regenerate and promote changes
55
-
dune build @gen --auto-promote
56
-
```
57
-
58
-
## Architecture
59
-
60
-
- `lib/openapi_spec.ml` - OpenAPI 3.x specification types with jsont codecs
61
-
- `lib/openapi_codegen.ml` - Code generation from spec to OCaml
62
-
- `lib/openapi_runtime.ml` - Runtime utilities for generated clients
63
-
- `bin/openapi_cli.ml` - CLI tool
64
-
65
-
## Build & Test
66
-
67
-
```bash
68
-
opam exec -- dune build
69
-
opam exec -- dune test
70
-
```
···
+15
LICENSE.md
+15
LICENSE.md
···
···
1
+
## ISC License
2
+
3
+
Copyright (c) Anil Madhavapeddy
4
+
5
+
Permission to use, copy, modify, and/or distribute this software for any
6
+
purpose with or without fee is hereby granted, provided that the above
7
+
copyright notice and this permission notice appear in all copies.
8
+
9
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
+
PERFORMANCE OF THIS SOFTWARE.
+8
-3
dune-project
+8
-3
dune-project
···
5
(generate_opam_files true)
6
7
(license ISC)
8
(authors "Anil Madhavapeddy")
9
-
(homepage "https://tangled.org/@anil.recoil.org/ocaml-openapi")
10
(maintainers "Anil Madhavapeddy <anil@recoil.org>")
11
-
(maintenance_intent "(latest)")
12
(source (tangled anil.recoil.org/ocaml-openapi))
13
14
(package
15
(name openapi)
16
(synopsis "OpenAPI code generator for OCaml with requests and jsont")
17
(description
18
"Generate type-safe OCaml API clients from OpenAPI 3.x specifications.
19
-
Uses the requests HTTP library and jsont for JSON codecs.")
20
(depends
21
(ocaml (>= 5.1.0))
22
jsont
···
5
(generate_opam_files true)
6
7
(license ISC)
8
+
9
(authors "Anil Madhavapeddy")
10
+
11
(maintainers "Anil Madhavapeddy <anil@recoil.org>")
12
+
13
(source (tangled anil.recoil.org/ocaml-openapi))
14
15
+
(homepage "https://tangled.org/@anil.recoil.org/ocaml-openapi")
16
+
17
+
(bug_reports "https://tangled.org/@anil.recoil.org/ocaml-openapi/issues")
18
+
19
(package
20
(name openapi)
21
(synopsis "OpenAPI code generator for OCaml with requests and jsont")
22
(description
23
"Generate type-safe OCaml API clients from OpenAPI 3.x specifications.
24
+
Uses the requests HTTP library and jsont for JSON codecs.")
25
(depends
26
(ocaml (>= 5.1.0))
27
jsont
+2
-2
openapi.opam
+2
-2
openapi.opam
···
3
synopsis: "OpenAPI code generator for OCaml with requests and jsont"
4
description: """
5
Generate type-safe OCaml API clients from OpenAPI 3.x specifications.
6
-
Uses the requests HTTP library and jsont for JSON codecs."""
7
maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]
8
authors: ["Anil Madhavapeddy"]
9
license: "ISC"
10
homepage: "https://tangled.org/@anil.recoil.org/ocaml-openapi"
11
-
bug-reports: "https://tangled.org/anil.recoil.org/ocaml-openapi/issues"
12
depends: [
13
"dune" {>= "3.21"}
14
"ocaml" {>= "5.1.0"}
···
3
synopsis: "OpenAPI code generator for OCaml with requests and jsont"
4
description: """
5
Generate type-safe OCaml API clients from OpenAPI 3.x specifications.
6
+
Uses the requests HTTP library and jsont for JSON codecs."""
7
maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]
8
authors: ["Anil Madhavapeddy"]
9
license: "ISC"
10
homepage: "https://tangled.org/@anil.recoil.org/ocaml-openapi"
11
+
bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-openapi/issues"
12
depends: [
13
"dune" {>= "3.21"}
14
"ocaml" {>= "5.1.0"}