package openapi

  1. Overview
  2. Docs
Openapi documentation infrastructure

Install

Dune Dependency

Authors

Maintainers

Sources

v1.0.1.tar.gz
md5=f96c9e50fbc5f09a66a6c5044dadc786
sha512=6419b8c5ec28d1a74c25607e69b2fa2a9eae5ff40b6a31674181e6d09cbcba71f97f925ac6cc69a9f9fc1eacd4f22b6499b7c6a7dd29919f6e8123140b4157e0

Description

Core types and functions for creating openapi compliant documentation using JSON schemas

Published: 16 Oct 2024

README

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

Dependencies (6)

  1. ppx_deriving >= "5.2.1"
  2. ppx_yojson_conv_lib >= "v0.16.0"
  3. ppx_yojson_conv >= "v0.16.0"
  4. core >= "v0.16.0"
  5. yojson >= "2.1.2"
  6. dune >= "2.8"

Dev Dependencies (1)

  1. odoc with-doc

Used by (2)

  1. openapi-opium >= "1.0.1"
  2. ppx_deriving_json_schema >= "1.0.1"

Conflicts

None

OCaml

Innovation. Community. Security.