ApiCodeGenerator.MSBuild 3.0.3

Read in Russian

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 application, which can be used to configure standard NSwag generators. The file has the following structure:

{
  "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 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 library. Requires the ApiCodeGenerator.OpenApi.Refit package.

Read about generator options:

• for all listed generators.
• for C# code generators
• for openApiToCSharpClient

Additionally, for all generators, the library adds the replaceNameCollection setting for replacing characters in property names.

"replaceNameCollection": {
  "@": "_" // Replace @ with _ in names
}