https://github.com/mobiletelesystems/apicodegenerator
Generate code from Swagger, OpenApi or AsyncApi documents.
https://github.com/mobiletelesystems/apicodegenerator
Last synced: 2 months ago
JSON representation
Generate code from Swagger, OpenApi or AsyncApi documents.
- Host: GitHub
- URL: https://github.com/mobiletelesystems/apicodegenerator
- Owner: MobileTeleSystems
- License: apache-2.0
- Created: 2024-09-23T12:44:10.000Z (over 1 year ago)
- Default Branch: dev
- Last Pushed: 2025-02-06T15:08:10.000Z (about 1 year ago)
- Last Synced: 2025-04-23T05:59:06.768Z (about 1 year ago)
- Language: C#
- Homepage:
- Size: 194 KB
- Stars: 24
- Watchers: 5
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.MD
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[Read in Russian](README_RU.MD)
[](https://www.nuget.org/packages/ApiCodeGenerator.MSBuild)
[](https://github.com/MobileTeleSystems/ApiCodeGenerator/blob/dev/LICENSE)
[](https://app.codacy.com/gh/MobileTeleSystems/ApiCodeGenerator/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
# How to install
1. Add the `ApiCodeGenerator.MSBuild` package in your project.
2. Add a file describing the API in formats like: Swagger 2.0, OpenApi 3.0, JsonSchema, AsyncApi 2.0 to your project.
3. Add a file with the same name but with the `.nswag` extension to your project and fill it out.
4. Rebuild the project.
# NSwag File Format
> To use hints while editing the file, set schema https://raw.githubusercontent.com/MobileTeleSystems/ApiCodeGenerator/refs/heads/dev/schemas/nswag.json .
The NSwag format consists of files that store settings for the [NSwagStudio](https://github.com/RicoSuter/NSwag/wiki/NSwagStudio) application, which can be used to configure standard NSwag generators.
The file has the following structure:
```json
{
"documentGenerator": {
"fromDocument": {
"json": "$(InputJson)",
"url": "http://basketService/swagger/v1/swagger.json"
}
},
"codeGenerators": {
"openApiToCSharpClient": {}
}
}
```
Since the settings for various APIs mostly overlap, to reduce duplication, you can move the settings for preprocessors and generators to a `base.nswag` file (the file name can be changed via settings). The file has the same structure, and the `codeGenerators` block can specify several generators (the settings for the selected generator will be applied to the target file). The file is searched in all higher-level directories starting from the NSwag file being generated.
## Document Generation
The `documentGenerator` block specifies the rules for obtaining the document based on which the code will be generated. For generation from documents in `Swagger 2.0`, `OpenApi 3.0`, or `AsyncApi 3.0` formats, you need to fill in the `fromDocument` property. For generation from a JsonSchema document, use the `jsonSchemaToOpenApi` property.
In `fromDocument`, the `json` property specifies the path to the file or a string containing the document itself (the example uses a variable containing the file path). The `url` property specifies the address from which the file can be downloaded. If the `json` property is not filled, the document will be downloaded from this address. Both properties can accept paths to YAML files.
> If paths are not specified in `fromDocument` or the block itself is absent, the `json` property will be set to the path from `OpenApiReference`.
Additionally, `fromDocument` can have a `preprocessors` property to connect handlers that preprocess the document before passing it to the code generator.
## Code Generation
The `codeGenerators` block specifies the generator that will be used to generate the code. The property name is the generator's name, and the value is the settings for the selected generator.
Available generators:
* `asyncApiToCSharpAmqpService` - C# client for the [RabbitMQ.Client 5](https://www.nuget.org/packages/RabbitMQ.Client/5.2.0) library.
* `openApiToCSharpClient` - generates a C# client for accessing the API.
* `openApiToCSharpController` - generates a controller and service interface for implementing the controller's logic.
* `openApiToRefitClient` - generates an interface for accessing the API using the [Refit](https://github.com/reactiveui/refit) library. Requires the [ApiCodeGenerator.OpenApi.Refit](https://github.com/MobileTeleSystems/ApiCodeGenerator.OpenApi.Refit) package.
Read about generator options:
- [for all listed generators](https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document).
- [for C# code generators](https://github.com/RicoSuter/NSwag/wiki/CSharpGeneratorBaseSettings)
- [for `openApiToCSharpClient`](https://github.com/RicoSuter/NSwag/wiki/CSharpClientGeneratorSettings)
Additionally, for all generators, the library adds the `replaceNameCollection` setting for replacing characters in property names.
```json
"replaceNameCollection": {
"@": "_" // Replace @ with _ in names
}