package ppx_deriving_json_schema
Install
Dune Dependency
Authors
Maintainers
Sources
md5=a2030ff58156b3ee639136749bb52c05
sha512=9538c197335653ad1699b488efdf0038b0c71a12ad69538190a4e8c69ca85d6e035ddae1f077bf8558355c75e82961049cb165489200a4f27e0695aba97f95a9
README.md.html
Openapi for Ocaml
This library provides basic types for parsing/serializing openapi specifications and a nearly drop-in replacement for Opium.App
that registers endpoints in a specification and serves openapi.json
and docs
pages based on the fastapi
implementation.
As of version 1.0.0, the Opium shim layer has been split out into a separate package (openapi-opium) from the core modules for creating Openapi compatible specifications (openapi). And a PPX has been introduced to (hopefully) accelerate JSON schema specification.
Usage
Basic usage should work equivalently to Opium.App
. So instead of
let open Opium in
App.empty
|> App.get "/path/:foo" (fun h -> Response.of_plain_text "hello world")
|> App.run_command
Just do:
let open Opium in
let module App = Openapi_opium.App in
App.empty
|> App.get "/path/:foo" (fun h -> Response.of_plain_text "hello world")
|> App.run_command
The endpoint creation methods provided by Openapi_opium.App
accept additional optional arguments to provide specification information for to document the endpoint. Check the type signatures of these methods for more information.
Demo App
This library includes a demo app in bin/demo
(that won't be installed by opam
). To see the generated spec/documentation in action, run:
$ dune build
$ ./_build/default/bin/demo.exe
Then browse to http://localhost:8888/docs
Ppx Deriving Json Schema
The openapi-ocaml repo also defines a ppx deriving plugin for generating JSON Schema values from OCaml type definitions. It supports record, polymorphic variant, tuple, and union datatypes.
Parameterized types are not properly handled.
The types 'a list
and 'a option
are handled specially using the JSON schema array
type and oneOf [null; 'a_schema]
respectively.
Installation
$ opam install ppx_deriving_json_schema
Usage
In your ocaml file:
type some_type = {int_field : int; string_field : string}
[@@deriving yojson, json_schema]
Will generate a value some_type_schema
defining a JSON schema compatible with JSON serialization produced by the ppx_json_conv
deriver.
Subschemas
By default, references to other types within the type definition are reflected as JSON schema references in the generated schema (see Attributes) below. The reference will take the form #/$defs/type_name_schema
for a reference to type type_name
.
The prefix (#/$defs/
) can be overriden using defs
argument to the deriver, as in:
type my_type { x : some_type }
[@@deriving yojson, json_schema {defs = "#/components/schemas"}]
Attributes
The JSON schema generator respects the @key
, @yojson.option
, @default
, @yojson.drop_*
and @name
attributes used by ppx_yojson_conv
to direct serialization/deserialization.
Additionally, the attribute @inline_schema
can be used to direct schema generation to inline the schema for a type reference (by inlining the result of type_name_schema
for a reference to the type type_name
) rather than using a schema reference