{"id":14986479,"url":"https://github.com/WojtekKarwacki/python-openapi-generator-rust","last_synced_at":"2025-06-13T08:07:42.381Z","repository":{"id":250371205,"uuid":"834278095","full_name":"wkarwacki/python-openapi-generator-rust","owner":"wkarwacki","description":"Typesafe Python Client and Server OpenAPI generator written in Rust / Trust","archived":false,"fork":false,"pushed_at":"2024-10-20T18:23:05.000Z","size":583,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-20T22:45:00.953Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"https://wkarwacki.github.io/python-openapi-generator-rust/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wkarwacki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T20:36:55.000Z","updated_at":"2024-10-20T18:23:09.000Z","dependencies_parsed_at":"2024-09-15T01:35:51.935Z","dependency_job_id":"b028b0d2-e81c-40cb-b24e-50edcb571c1a","html_url":"https://github.com/wkarwacki/python-openapi-generator-rust","commit_stats":{"total_commits":197,"total_committers":1,"mean_commits":197.0,"dds":0.0,"last_synced_commit":"7bb3c7819d44bf1344424486c004ff5d840da7f1"},"previous_names":["wkarwacki/trust"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkarwacki%2Fpython-openapi-generator-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkarwacki%2Fpython-openapi-generator-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkarwacki%2Fpython-openapi-generator-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkarwacki%2Fpython-openapi-generator-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wkarwacki","download_url":"https://codeload.github.com/wkarwacki/python-openapi-generator-rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482928,"owners_count":21111402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-09-24T14:12:56.278Z","updated_at":"2025-06-13T08:07:41.896Z","avatar_url":"https://github.com/wkarwacki.png","language":"Rust","readme":"\u003cp\u003e\n  \u003cb\u003ePython Server OpenAPI Generator, Python Client OpenAPI Generator, Kotlin Server OpenAPI Generator\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eDocumentation, source code: \u003ca href=\"https://github.com/wkarwacki/python-openapi-generator-rust\" target=\"_blank\"\u003ehttps://github.com/wkarwacki/python-openapi-generator-rust\u003c/a\u003e\u003c/b\u003e\n\u003c/p\u003e\n\n---\n# Trust Spec\n\nTrust 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.\n\n## Table of Contents\n- [I just want to glue my services together](#i-just-want-to-glue-my-services-together)\n- [Requirements](#requirements)\n- [Specification](#specification)\n  - [Overview](#overview)\n  - [Common Use Cases](#common-use-cases)\n- [Code Generation](#code-generation)\n  - [Generator Options](#generator-options)\n  - [Supported Generators](#supported-generators)\n    - [Experimental Generators](#experimental-generators)\n  - [Generators Documentation](#generators-documentation)\n- [Conversion from OpenAPI](#conversion-from-openapi)\n- [Conversion to OpenAPI](#conversion-to-openapi)\n- [Building Trust CLI](#building-trust-cli)\n  - [With Docker](#with-docker)\n  - [From Source](#from-source)\n\n## I just want to glue my services together\nInstall Trust:\n```shell\n$ pip install trustspeccli\n```\nThen, run:\n```shell\n$ trust\n\nUsage: trust \u003cCOMMAND\u003e\n\nCommands:\n  from-open-api  Convert an OpenAPI specification to a Trust specification. Integrate this into your build process to utilize Trust's code generators\n  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\n  generate       Generate code based on a Trust specification\n  help           Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\n- If you already have an OpenAPI spec:\n  1. first convert it to Trust spec with `from-open-api` command\n  2. and then generate the glue code with `generate` command.\n\n  \u003e :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.\n\n- **Without an OpenAPI spec:**\n  - Start directly with Trust spec.\n\n- **To continue using OpenAPI for code generation:**\n  - Use Trust spec as an intermediate format with the `to-open-api` command.\n\n## Requirements\n- Python 3.10 - currently the only supported version\n\n## Specification\nTrust specification enhances current integration standards like [OpenAPI](https://github.com/OAI/OpenAPI-Specification). Key benefits include:\n- **Clear Notation** - Single way to model and interpret an API.\n- **Generic Types** - Customizable types with parameters for different contexts.\n- **Minimalistic** - Simple, efficient language without redundant features.\n- **Web System Integration Focused** - Ideal for type-safe system integration.\n- **Highly Customizable** - Extensive [handlebars](https://github.com/sunng87/handlebars-rust) helpers for template modification.\n- **Protocol-Agnostic** - Designed for HTTP but applicable to any API type.\n\nIt addresses inherent OpenAPI issues with:\n- **Enclosed Algebraic Data Types** - All subtypes of an ADT are grouped in a single `adt` node.\n\n### Overview\nExamples and more usage details can be found in [tests](https://github.com/wkarwacki/python-openapi-generator-rust/tree/master/src/lib/test).\n\n**Data Types:**\n- **Simple Types:**\n  - `type: bool` - equivalent to OpenAPI `type: boolean`\n  - `type: int` - equivalent to OpenAPI `type: integer` with `format: int64`\n  - `type: dec` - equivalent to OpenAPI `type: number`\n  - `type: str` - equivalent to OpenAPI `type: string`\n  - `type: enum` - equivalent to OpenAPI `type: string` with `enum`\n- **Complex Types:**\n  - `type: obj` - equivalent to OpenAPI `type: object`\n  - `type: seq` - equivalent to OpenAPI `type: array`\n  - `type: map` - equivalent to OpenAPI `type: object` with `additionalProperties`\n- **Special Types:**\n  - `type: alias` - equivalent to OpenAPI `$ref`\n  - `type: struct` - equivalent to OpenAPI empty schema (`{}`)\n  - `type: const` - equivalent to OpenAPI `const`\n\n### Common Use Cases\n\n**Including Variables from Other Types:**\n  ```yaml\n  Parent:\n    type: obj\n    vars:\n      parentVar:\n        type: dec\n  AnotherParent:\n    type: obj\n    vars:\n      anotherParentVar:\n        type: bool\n  WithParentsVars:\n    type: obj\n    mix:\n      - path: \"defs.Parent\"\n      - path: \"defs.AnotherParent\"\n    vars:\n      ownVar:\n        type: int\n  ```\nResults in:\n  ```json\n  {\n    \"parentVar\": 1.0,\n    \"anotherParentVar\": true,\n    \"ownVar\": 1\n  }\n  ```\n\n**Algebraic Data Types (Union Types):**\n  ```yaml\n  AdtType:\n    type: obj\n    vars: \n      discriminatorVar:\n        type: str\n      someOtherVar:\n        type: dec\n    adt:\n      var: discriminatorVar\n      map:\n        firstSubtype:\n          vars:\n            firstSubtypeVar:\n              type: int\n        secondSubtype:\n          vars:\n            secondSubtypeVar:\n              type: bool\n  ```\nInterpreted as:\n  ```json\n  {\n    \"discriminatorVar\": \"firstSubtype\",\n    \"someOtherVar\": 1.0,\n    \"firstSubtypeVar\": 1\n  }\n  ```\n  ```json\n  {\n    \"discriminatorVar\": \"secondSubtype\",\n    \"someOtherVar\": 1.0,\n    \"secondSubtypeVar\": true\n  }\n  ```\n\n\n**Generic Types:**\n  ```yaml\n  defs:\n    SomeNamedString:\n      type: str\n    ParameterizedType:\n      type: obj\n      vars:\n        varOfParamAbcType:\n          param: ParamAbc # to declare a generic type, you need to simply use a 'param' keyword\n        varOfParamXyzType:\n          param: ParamXyz # similarly to the above, this time with a different name\n        anoterVarOfParamXyzType:\n          param: ParamXyz # similarly to the above, this time with a different name\n    SubtypeOfParameterizedType:\n      type: obj\n      ext: # extending a generic type\n        path: 'defs.ParameterizedType'\n        args: # with below type-arguments\n          ParamAbc:\n            type: bool\n          ParamXyz:\n            path: 'defs.SomeType'\n  ```\nEquivalent to:\n  ```java\n  interface ParameterizedType\u003cParamAbc, ParamXyz\u003e { \n    ParamAbc varOfParamAbcType; \n    ParamXyz varOfParamXyzType; \n    ParamXyz anoterVarOfParamXyzType; \n  }\n  interface SubtypeOfParameterizedType extends ParameterizedType\u003cBoolean, SomeType\u003e { }\n  ```\n\n## Code Generation\n\n```shell\n$ trust generate -h\nGenerate code based on a Trust specification\n\nUsage: trust generate [OPTIONS] \u003cLANG\u003e \u003cROLE\u003e \u003cINPUT\u003e \u003cOUTPUT\u003e\n\nArguments:\n  \u003cLANG\u003e    Select the target programming language for the generated code [possible values: kotlin, python, scala, type-script]\n  \u003cROLE\u003e    Specify whether to generate server or client code [possible values: client, server]\n  \u003cINPUT\u003e   Path to the Trust specification file\n  \u003cOUTPUT\u003e  Directory where the generated code will be saved\n\nOptions:\n  -c \u003cCONFIG\u003e              Optional path to a generator configuration file. Refer to the Trust documentation for details\n  -t \u003cTEMPLATES_PATH\u003e      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\n  -h, --help               Print help\n```\n\n### Generator Options\nYou can customize the generator behavior by passing a relevant `yml` configuration file. The following options are available:\n* `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.\n* `module: str` - Specify the module name for the generated code\n* `dtoName: str` - Provide the custom Handlebars template for naming DTO classes, by default it is `{{val}}Dto`\n* `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).\n  * For server generators - Provides default implementation for all the operations\n  * For client generators - Generates tests with all required params that verify server's correctness \n\n### Supported Generators:\n\n- \u003cb\u003ePython HTTP Server ([fastapi](https://github.com/tiangolo/fastapi))\u003c/b\u003e\n- \u003cb\u003ePython HTTP Client ([httpx](https://github.com/encode/httpx))\u003c/b\u003e\n\n#### Experimental Generators:\n\u003e :exclamation: Not fully implemented. Use at your own risk.\n\n- Kotlin HTTP Server ([spring](https://github.com/spring-projects/spring-framework))\n- Scala HTTP Server ([cask](https://github.com/com-lihaoyi/cask))\n\n### Generators Documentation\nFor detailed documentation, features and limitations on the supported code generators, refer to:\n- [Python Http Client Generator Documentation](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/src/lib/gen/python/client/Readme.md)\n- [Python Http Server Generator Documentation](https://github.com/wkarwacki/python-openapi-generator-rust/blob/master/src/lib/gen/python/server/Readme.md)\n\n\n## Conversion from OpenAPI\n```shell\n$ trust from-open-api -h\nConvert an OpenAPI specification to a Trust specification. Integrate this into your build process to utilize Trust's code generators\n\nUsage: trust from-open-api [OPTIONS] \u003cINPUT\u003e \u003cOUTPUT\u003e\n\nArguments:\n  \u003cINPUT\u003e   Path to the OpenAPI specification file\n  \u003cOUTPUT\u003e  Directory where the output Trust specification will be saved\n\nOptions:\n  -l \u003cLAYOUT\u003e      Specify the structure of the converted Trust specification [default: default] [possible values: default, tag]\n  -h, --help       Print help (see more with '--help')\n\n```\n* 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).\n\n## Conversion to OpenAPI\n\n```shell\n$ trust to-open-api -h\nConvert a Trust specification back to an OpenAPI specification, useful when a Trust code generator is not available for your target language\n\nUsage: trust to-open-api \u003cINPUT\u003e\n\nArguments:\n  \u003cINPUT\u003e  Path to the Trust specification file\n\nOptions:\n  -h, --help  Print help\n```\n\n## Building Trust Cli\n\n### With Docker\nPrerequisites:\n- [Docker](https://docs.docker.com/engine/install/)\n  ```shell\n  $ ./docker/build.sh\n  $ docker run trust\n  ```\n\n### From Source\nPrerequisites:\n- [Rust](https://www.rust-lang.org/tools/install)\n  ```shell\n  $ cargo run trust\n  ```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWojtekKarwacki%2Fpython-openapi-generator-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWojtekKarwacki%2Fpython-openapi-generator-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWojtekKarwacki%2Fpython-openapi-generator-rust/lists"}