Python Server OpenAPI Generator, Python Client OpenAPI Generator, Kotlin Server OpenAPI Generator

---

Documentation, source code: https://github.com/wkarwacki/python-openapi-generator-rust

---

Trust Spec

Trust Spec is a web integration specification and a set of code generators aiming to be a substitute for OpenAPI. It provides a unified way to describe data transfer interfaces and generates modern, type-safe code.

Table of Contents

• I just want to glue my services together
• Specification
  • Overview
  • Common Use Cases
• Code Generation
  • Generator Options
  • Supported Generators
    • Experimental Generators
  • Generators Documentation
• Conversion from OpenAPI
• Conversion to OpenAPI
• Building Trust CLI
  • With Docker
  • From Source

I just want to glue my services together

Install Trust:

$ pip install trustspeccli

Then, run:

$ trust

Usage: trust <COMMAND>

Commands:
  from-open-api  Convert an OpenAPI specification to a Trust specification. Integrate this into your build process to utilize Trust code generators
  to-open-api    Convert a Trust specification back to an OpenAPI specification, useful when a Trust code generator is not available for your target language
  generate       Generate code based on a Trust specification
  help           Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

• If you already have an OpenAPI spec:

  1. first convert it to Trust spec with from-open-api command
  2. and then generate the glue code with generate command.

  ❗ Note that you may easily automate the whole process combining the two steps above, however it is recommended to make a migration once and leverage Trust spec's expressiveness in long-term.

• Without an OpenAPI spec:

  • Start directly with Trust spec.

• To continue using OpenAPI for code generation:

  • Use Trust spec as an intermediate format with the to-open-api command.

Specification

Trust specification enhances current integration standards like OpenAPI. Key benefits include:

• Clear Notation - Single way to model and interpret an API.
• Generic Types - Customizable types with parameters for different contexts.
• Minimalistic - Simple, efficient language without redundant features.
• Web System Integration Focused - Ideal for type-safe system integration.
• Highly Customizable - Extensive handlebars helpers for template modification.
• Protocol-Agnostic - Designed for HTTP but applicable to any API type.

It addresses inherent OpenAPI issues with:

• Enclosed Algebraic Data Types - All subtypes of an ADT are grouped in a single adt node.

Overview

Examples and more usage details can be found in tests.

Data Types:

• Simple Types:
  • type: bool - equivalent to OpenAPI type: boolean
  • type: int - equivalent to OpenAPI type: integer with format: int64
  • type: dec - equivalent to OpenAPI type: number
  • type: str - equivalent to OpenAPI type: string
  • type: enum - equivalent to OpenAPI type: string with enum
• Complex Types:
  • type: obj - equivalent to OpenAPI type: object
  • type: seq - equivalent to OpenAPI type: array
  • type: map - equivalent to OpenAPI type: object with additionalProperties
• Special Types:
  • type: alias - equivalent to OpenAPI $ref
  • type: struct - equivalent to OpenAPI empty schema ({})
  • type: const - equivalent to OpenAPI const

Common Use Cases

Including Variables from Other Types:

Parent:
  type: obj
  vars:
    parentVar:
      type: dec
AnotherParent:
  type: obj
  vars:
    anotherParentVar:
      type: bool
WithParentsVars:
  type: obj
  mix:
    - path: "defs.Parent"
    - path: "defs.AnotherParent"
  vars:
    ownVar:
      type: int

Results in:

{
  "parentVar": 1.0,
  "anotherParentVar": true,
  "ownVar": 1
}

Algebraic Data Types (Union Types):

AdtType:
  type: obj
  vars: 
    discriminatorVar:
      type: str
    someOtherVar:
      type: dec
  adt:
    var: discriminatorVar
    map:
      firstSubtype:
        vars:
          firstSubtypeVar:
            type: int
      secondSubtype:
        vars:
          secondSubtypeVar:
            type: bool

Interpreted as:

{
  "discriminatorVar": "firstSubtype",
  "someOtherVar": 1.0,
  "firstSubtypeVar": 1
}

{
  "discriminatorVar": "secondSubtype",
  "someOtherVar": 1.0,
  "secondSubtypeVar": true
}

Generic Types:

defs:
  SomeNamedString:
    type: str
  ParameterizedType:
    type: obj
    vars:
      varOfParamAbcType:
        param: ParamAbc # to declare a generic type, you need to simply use a 'param' keyword
      varOfParamXyzType:
        param: ParamXyz # similarly to the above, this time with a different name
      anoterVarOfParamXyzType:
        param: ParamXyz # similarly to the above, this time with a different name
  SubtypeOfParameterizedType:
    type: obj
    ext: # extending a generic type
      path: 'defs.ParameterizedType'
      args: # with below type-arguments
        ParamAbc:
          type: bool
        ParamXyz:
          path: 'defs.SomeType'

Equivalent to:

interface ParameterizedType<ParamAbc, ParamXyz> { 
  ParamAbc varOfParamAbcType; 
  ParamXyz varOfParamXyzType; 
  ParamXyz anoterVarOfParamXyzType; 
}
interface SubtypeOfParameterizedType extends ParameterizedType<Boolean, SomeType> { }

Code Generation

$ trust generate -h
Generate code based on a Trust specification

Usage: trust generate [OPTIONS] <LANG> <ROLE> <INPUT> <OUTPUT>

Arguments:
  <LANG>    Select the target programming language for the generated code [possible values: kotlin, python, scala, type-script]
  <ROLE>    Specify whether to generate server or client code [possible values: client, server]
  <INPUT>   Path to the Trust specification file
  <OUTPUT>  Directory where the generated code will be saved

Options:
  -c <CONFIG>              Optional path to a generator configuration file. Refer to the Trust documentation for details
  -t <TEMPLATES_PATH>      Optional path to a custom templates directory. For instance, you can override any template found at https://github.com/wkarwacki/python-openapi-generator-rust/tree/master/src/lib/gen/python/server/templates, however this can be configured for all languages and roles
  -h, --help               Print help

Generator Options

You can customize the generator behavior by passing a relevant yml configuration file. The following options are available:

• typeMapping: dict[str, str] - Map Trust Spec type to any provided type in a type-safe way. Generated code for both server and client is supposed to pick up on mapping provided by the user so that any errors in such will be caught at compile time.
• module: str - Specify the module name for the generated code
• dtoName: str - Provide the custom Handlebars template for naming DTO classes, by default it is {{val}}Dto
• autoImplement: bool This option is a fundamental part of the Trust Spec integration tests suite.
  • For server generators - Provides default implementation for all the operations
  • For client generators - Generates tests with all required params that verify server's correctness

Supported Generators:

• Python HTTP Server (fastapi)
• Python HTTP Client (httpx)

Experimental Generators:

❗ Not fully implemented. Use at your own risk.

• Kotlin HTTP Server (spring)
• Scala HTTP Server (cask)

Generators Documentation

For detailed documentation, features and limitations on the supported code generators, refer to:

• Python Http Client Generator Documentation
• Python Http Server Generator Documentation

Conversion from OpenAPI

$ trust from-open-api -h
Convert an OpenAPI specification to a Trust specification. Integrate this into your build process to utilize Trust's code generators

Usage: trust from-open-api [OPTIONS] <INPUT> <OUTPUT>

Arguments:
  <INPUT>   Path to the OpenAPI specification file
  <OUTPUT>  Directory where the output Trust specification will be saved

Options:
  -l <LAYOUT>      Specify the structure of the converted Trust specification [default: default] [possible values: default, tag]
  -h, --help       Print help (see more with '--help')

• Control the layout of the generated Trust spec with the -l option. For instance, setting it to tag organizes the Trust spec by OpenAPI tags, as shown in this example.

Conversion to OpenAPI

$ trust to-open-api -h
Convert a Trust specification back to an OpenAPI specification, useful when a Trust code generator is not available for your target language

Usage: trust to-open-api <INPUT>

Arguments:
  <INPUT>  Path to the Trust specification file

Options:
  -h, --help  Print help

Building Trust Cli

With Docker

Prerequisites:

• Docker

  $ ./docker/build.sh
  $ docker run trust

From Source

Prerequisites:

• Rust

  $ cargo run trust