Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wkarwacki/python-openapi-generator-rust

Typesafe Python Client and Server OpenAPI generator written in Rust / Trust
https://github.com/wkarwacki/python-openapi-generator-rust

fastapi generator http http-client http-server httpx-client integration kotlin openapi openapi-codegen openapi-generator openapi-specification openapi3 openapi31 python python-3 python3 rust scala specification

Last synced: 1 day ago
JSON representation

Typesafe Python Client and Server OpenAPI generator written in Rust / Trust

Awesome Lists containing this project

README 

        


  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](#i-just-want-to-glue-my-services-together)

- [Specification](#specification)

  - [Overview](#overview)

  - [Common Use Cases](#common-use-cases)

- [Code Generation](#code-generation)

  - [Generator Options](#generator-options)

  - [Supported Generators](#supported-generators)

    - [Experimental Generators](#experimental-generators)

  - [Generators Documentation](#generators-documentation)

- [Conversion from OpenAPI](#conversion-from-openapi)

- [Conversion to OpenAPI](#conversion-to-openapi)

- [Building Trust CLI](#building-trust-cli)

  - [With Docker](#with-docker)

  - [From Source](#from-source)



## I just want to glue my services together

Install Trust:

```shell

$ pip install trustspeccli

```

Then, run:

```shell

$ trust



Usage: trust 



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.



  > :exclamation: 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](https://github.com/OAI/OpenAPI-Specification). 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](https://github.com/sunng87/handlebars-rust) 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](https://github.com/wkarwacki/python-openapi-generator-rust/tree/master/src/lib/test).



**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:**

  ```yaml

  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:

  ```json

  {

    "parentVar": 1.0,

    "anotherParentVar": true,

    "ownVar": 1

  }

  ```



**Algebraic Data Types (Union Types):**

  ```yaml

  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:

  ```json

  {

    "discriminatorVar": "firstSubtype",

    "someOtherVar": 1.0,

    "firstSubtypeVar": 1

  }

  ```

  ```json

  {

    "discriminatorVar": "secondSubtype",

    "someOtherVar": 1.0,

    "secondSubtypeVar": true

  }

  ```



**Generic Types:**

  ```yaml

  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:

  ```java

  interface ParameterizedType { 

    ParamAbc varOfParamAbcType; 

    ParamXyz varOfParamXyzType; 

    ParamXyz anoterVarOfParamXyzType; 

  }

  interface SubtypeOfParameterizedType extends ParameterizedType { }

  ```



## Code Generation



```shell

$ trust generate -h

Generate code based on a Trust specification



Usage: trust generate [OPTIONS]    



Arguments:

      Select the target programming language for the generated code [possible values: kotlin, python, scala, type-script]

      Specify whether to generate server or client code [possible values: client, server]

     Path to the Trust specification file

    Directory where the generated code will be saved



Options:

  -c               Optional path to a generator configuration file. Refer to the Trust documentation for details

  -t       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](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/do_test.sh#L13).

  * 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](https://github.com/tiangolo/fastapi))

- Python HTTP Client ([httpx](https://github.com/encode/httpx))



#### Experimental Generators:

> :exclamation: Not fully implemented. Use at your own risk.



- Kotlin HTTP Server ([spring](https://github.com/spring-projects/spring-framework))

- Scala HTTP Server ([cask](https://github.com/com-lihaoyi/cask))



### Generators Documentation

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

- [Python Http Client Generator Documentation](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/src/lib/gen/python/client/Readme.md)

- [Python Http Server Generator Documentation](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/src/lib/gen/python/server/Readme.md)



## Conversion from OpenAPI

```shell

$ 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]  



Arguments:

     Path to the OpenAPI specification file

    Directory where the output Trust specification will be saved



Options:

  -l       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](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/test/integration/specs/openapi_fastapi/api.yml#L9).



## Conversion to OpenAPI



```shell

$ 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 



Arguments:

    Path to the Trust specification file



Options:

  -h, --help  Print help

```



## Building Trust Cli



### With Docker

Prerequisites:

- [Docker](https://docs.docker.com/engine/install/)

  ```shell

  $ ./docker/build.sh

  $ docker run trust

  ```



### From Source

Prerequisites:

- [Rust](https://www.rust-lang.org/tools/install)

  ```shell

  $ cargo run trust

  ```