daml-oas

Generate OpenAPI 3.1 and AsyncAPI specification documents for the Daml JSON API from a Dar file.

Install

cargo install daml-oas

Usage

Generate OpenAPI and AsyncAPI specification documents for the Daml JSON API from a Dar file:

USAGE:
    daml-oas [SUBCOMMAND]

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    a2s     Generate an AsyncAPI document from the given Dar file
    help    Print this message or the help of the given subcommand(s)
    oas     Generate an OpenAPI document from the given Dar file

OpenAPI Usage

To generate an OpenAPI document from the given Dar file:

USAGE:
    daml-oas oas [OPTIONS] <dar>

ARGS:
    <dar>    Sets the input dar file to use

OPTIONS:
    -c, --companion-file <companion-file>
            the companion yaml file with auxiliary data to inject into the generated OAS document

    -d, --datadict-file <datadict-file>
            the data dictionary to use to augment the generated JSON schema

        --data-title <data-title>
            include the `title` property describing the data item name (i.e. Foo.Bar:Baz) [default:
            data] [possible values: none, data]

    -f, --format <format>
            the output format [default: json] [possible values: json, yaml]

    -h, --help
            Print help information

        --include-archive-choice
            include the Archive choice which is available on every template

        --include-general-operations
            include the general (non-template specific) /v1/create, /v1/exercise, /v1/create-and-
            exercise & /v1/fetch endpoints

        --include-package-id
            include the package id in fully qualified templates

    -m, --module <module-path>
            module path prefix in the form Foo.Bar.Baz

    -o, --output <output>
            the output file path

    -p, --reference-prefix <reference-prefix>
            the prefix for absolute $ref schema references [default: #/components/schemas/]

    -r, --reference-mode <reference-mode>
            encode references as as $ref schema links or inline [default: ref] [possible values:
            ref, inline]

    -s, --path-style <path-style>
            encode paths with fragment (i.e. '#') or slash ('/') [default: fragment] [possible
            values: fragment, slash]

    -t, --template-filter-file <template-filter-file>
            the template filter to apply

        --type-description <type-description>
            include the `description` property describing the Daml type [default: all] [possible
            values: none, data, all]

    -v
            Sets the level of verbosity

To generate an AsyncAPI document from the given Dar file:

AsyncAPI Usage

USAGE:
    daml-oas a2s [OPTIONS] <dar>

ARGS:
    <dar>    Sets the input dar file to use

OPTIONS:
    -c, --companion-file <companion-file>
            the companion yaml file with auxiliary data to inject into the generated OAS document

    -d, --datadict-file <datadict-file>
            the data dictionary to use to augment the generated JSON schema

        --data-title <data-title>
            include the `title` property describing the data item name (i.e. Foo.Bar:Baz) [default:
            data] [possible values: none, data]

    -f, --format <format>
            the output format [default: json] [possible values: json, yaml]

    -h, --help
            Print help information

        --include-package-id
            include the package id in fully qualified templates

    -m, --module <module-path>
            module path prefix in the form Foo.Bar.Baz

    -o, --output <output>
            the output file path

    -p, --reference-prefix <reference-prefix>
            the prefix for absolute $ref schema references [default: #/components/schemas/]

    -r, --reference-mode <reference-mode>
            encode references as as $ref schema links or inline [default: ref] [possible values:
            ref, inline]

    -t, --template-filter-file <template-filter-file>
            the template filter to apply

        --type-description <type-description>
            include the `description` property describing the Daml type [default: all] [possible
            values: none, data, all]

    -v
            Sets the level of verbosity

Examples

OpenAPI

Generate an OpenAPI specification for MyModel.dar in json format:

daml-oas oas MyModel.dar

Generate an OpenAPI specification for MyModel.dar in yaml format with documentation augmented from .companion.yaml, a data dictionary from .datadict.yaml and filtered for the templates and choices specified by .template_filter.yaml:

daml-oas oas MyModel.dar -f yaml -c .companion.yaml -d .datadict.yaml -f .template_filter.yaml

AsyncAPI

Generate an AsyncAPI specification for MyModel.dar in json format:

daml-oas oas MyModel.dar

Companion File

The companion yaml file contains additional documentation about templates and choices as well as other metadata that will be used to augment the generated OpenAPI and AsyncAPI specifications.

All fields are non-mandatory and any subset of operations may be documented.

Example

title: MyApp 1.0 API Documentation
summary: MyApp Daml JSON API
description: OpenAPI specification for MyApp Daml JSON API
version: 1.9.9
contact:
  name: Bob Smith
  url: https://example.com/myapp
  email: bob.smith@example.com
servers:
  - http://localhost:7575
operations:
  Fuji.PingPong:Pong:
    create: create a Pong!
    createAndExercise:
      RespondPing: create a Pong and then respond with a Ping
    exerciseById:
      RespondPing: respond with a Ping by id
      Archive: archive the contract by id
    exerciseByKey:
      RespondPing: respond with a Ping by key
      Archive: archive the contract by key
    fetchById: fetch a Pong contract by id from the ledger
    fetchByKey: fetch a Pong contract by key from the ledger

Datadict File

The datadict yaml file contains additional documentation for Daml records that will be used to augment the generated OpenAPI and AsyncAPI specifications.

Any documentation provided in this file will be used in preference to any automatically produced documentation in the output. This datadict can contain documentation for any subset of templates and fields.

Example

Fuji.Vehicle:Car:
  title: My Custom Title
  description: Represents a Car
  items:
    driver: the driver of the car
    make: the make of the car
    owner: the owner of the car
    purchase_time: when the car was purchased
    reg_year: the registration year
Fuji.PingPong:Ping:
  description: The demo Ping template
  items:
    count: the number of times ping has ponged

Template Filter File

The template filter yaml file allows you to specify a subset of templates and choices to generate.

If a template filter file is provided (using the --template-filter-file option) then it will act as an inclusive list, any template or choice not specified will be omitted. To include all templates and choices in the output you must omit the --template-filter-file argument.

For each template, you must specify either all choices or a list of selected choice names.

Example

Fuji.Nested:NestedTemplate: all
Fuji.PingPong:Ping:
  selected:
    - RespondPong
    - ResetPingCount
Fuji.PingPong:Pong:
  selected:
    - RespondPing
Fuji.Shape:CircleTemplate: all
Fuji.DupUsage:DupUsage: all

Render

The generated OpenAPI and AsyncAPI specifications can be processed with any tool that supports the relevant standard. The following html examples uses the stoplight.io library to render an OpenAPI specification:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Elements in HTML</title>
    <!-- Embed elements Elements via Web Component -->
    <script src="https://unpkg.com/@stoplight/elements@beta/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@beta/styles.min.css">
</head>
<body>

<elements-api
        apiDescriptionUrl="https://gist.githubusercontent.com/fujiapple852/openapi-example.json"
        router="hash"
        layout="sidebar"
/>

</body>
</html>

Build Standalone Executable

To build and run daml-oas as a standalone (using musl) executable, first build the rust-musl Docker image (run from rust-daml-bindings/examples/daml-oas):

make build-image

Generate the daml-oas executable using musl:

make build

Run the generated artifact on a vanilla centos Docker image:

make run-oas dar=rust/resources/testing_types_sandbox/TestingTypes-latest.dar

License

daml-oas is distributed under the terms of the Apache License (Version 2.0).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in time by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See LICENSE for details.

Copyright 2022