daml-oas

从Dar文件生成Daml JSON API的OpenAPI 3.1和AsyncAPI规范文档。

安装

cargo install daml-oas

用法

从Dar文件生成Daml JSON API的OpenAPI和AsyncAPI规范文档

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用法

从给定的Dar文件生成OpenAPI文档

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

从给定的Dar文件生成AsyncAPI文档

AsyncAPI用法

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

示例

OpenAPI

以JSON格式生成MyModel.dar的OpenAPI规范

daml-oas oas MyModel.dar

以yaml格式生成MyModel.dar的OpenAPI规范，文档增强来自.companion.yaml、.datadict.yaml的数据字典以及由.template_filter.yaml指定的模板和选择的过滤

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

AsyncAPI

以JSON格式生成MyModel.dar的AsyncAPI规范

daml-oas oas MyModel.dar

配套文件

配套的yaml文件包含有关模板和选择的额外文档以及其他将用于增强生成的OpenAPI和AsyncAPI规范的其他元数据。

所有字段都是非必填的，可以记录任何操作子集。

示例

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: [email protected]
servers:
  - https://127.0.0.1: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 yaml文件包含用于增强生成的OpenAPI和AsyncAPI规范的Daml记录的额外文档。

在此文件中提供的任何文档都将优先于输出中自动生成的任何文档。此数据字典可以包含任何模板和字段的文档。

示例

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

模板过滤器文件

模板过滤器yaml文件允许您指定要生成的模板和选择的子集。

如果提供了模板过滤器文件（使用--template-filter-file选项），则它将作为一个包含列表，任何未指定的模板或选择将被省略。要包括输出中的所有模板和选择，必须省略--template-filter-file参数。

对于每个模板，您必须指定all选项或一个选定的选项名称列表。

示例

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

渲染

生成的OpenAPI和AsyncAPI规范可以使用支持相关标准的任何工具进行处理。以下html示例使用stoplight.io库来渲染OpenAPI规范

<!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>

构建独立可执行文件

要将daml-oas构建并作为独立可执行文件运行（使用musl），首先构建rust-musl Docker镜像（从rust-daml-bindings/examples/daml-oas运行）

make build-image

使用musl生成daml-oas可执行文件

make build

在普通的centos Docker镜像上运行生成的工件

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

许可证

daml-oas在Apache许可证（版本2.0）的条款下分发。

除非你明确声明，否则根据Apache-2.0许可证定义，你有意提交的任何贡献都应双重许可如上所述，没有额外的条款或条件。

有关详细信息，请参阅LICENSE。

版权所有 2022