SDK in [Your Language]

1. 1. Choose a Generation Tool

   2. Install the Tool

   3. Generate the SDK

   4. Integrate and Use the SDK

Comparison of SDK Generation Tools and Supported Languages

OpenAPI Generator

• Overview and Supported Languages

  OpenAPI Generator is one of the most popular and actively maintained tools for generating SDKs (SDK Generation from an OpenAPI Specification File | James Sevedge). It is a community-driven fork of the original Swagger Codegen project, offering more features and faster updates. OpenAPI Generator supports over 50 client generators covering a wide array of languages and frameworks (Hello from OpenAPI Generator | OpenAPI Generator). This includes all major languages (Java, C#, Python, JavaScript/TypeScript, PHP, Ruby, Go, etc.) and many others (Swift, Kotlin, Scala, Rust, Dart, etc.). In addition to client libraries, it can also generate server stubs and API documentation. The tool uses Mustache templates for code generation, which can be customized if you need to tweak the output (Hello from OpenAPI Generator | OpenAPI Generator).

  Installation

  OpenAPI Generator is Java-based but can be used through various convenient distributions:

  • NPM (Node.js): Install the CLI globally using Node’s package manager. For example: npm install @openapitools/openapi-generator-cli -g. This provides the openapi-generator-cli command (Hello from OpenAPI Generator | OpenAPI Generator).

  • Homebrew (macOS): If you use Homebrew, you can install it with one command: brew install openapi-generator (Hello from OpenAPI Generator | OpenAPI Generator).

  • Docker: OpenAPI Generator provides a Docker image so you can run it without installing Java. For example: docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -i /local/openapi.json -g go -o /local/out/go will generate a Go client, given an OpenAPI file mounted at /local (Hello from OpenAPI Generator | OpenAPI Generator).

  • Executable JAR: You can alsPrepare the OpenAPI Spec

    Choose a Generation Tool

    Install the Tool

    Generate the SDK

    Integrate and Use the SDK

  • o download the standalone JAR from the OpenAPI Generator release page and run it with java -jar. (Ensure you have Java 8+ installed.)

  After installation, verify by running openapi-generator-cli --help to see available commands.

  Generating an SDK with OpenAPI Generator

  To generate an SDK, use the generate command. You must specify the input spec file (-i), a generator template (language) (-g), and an output directory (-o). For example, to generate a Ruby client SDK from an OpenAPI spec file:

  openapi-generator-cli generate -i petstore.yaml -g ruby -o /tmp/test/ ([Hello from OpenAPI Generator | OpenAPI Generator](https://openapi-generator.tech?utm_source=openapi-tools&utm_medium=website&utm_campaign=sdk#:~:text=openapi,o%20%2Ftmp%2Ftest))
  

  This will create a Ruby SDK in the /tmp/test folder (using the built-in Ruby templates). Likewise, to generate a Python client, you would specify -g python, or for Java -g java, etc. OpenAPI Generator has specific generator names for different languages/frameworks (run openapi-generator-cli list to see all). Common ones include java, python, typescript-fetch (TypeScript client using Fetch API), csharp (C# .NET), go, php, swift and many more.

  Configuration Options: You can pass additional options via -p (individual properties) or -c (JSON/YAML config file) to customize the generated code (package names, file naming, etc.). For example, you might set a package name or API class name. OpenAPI Generator’s website and help output detail these options for each language.

  Custom Templates: If the default code style doesn’t suit you, OpenAPI Generator allows customization. All generators use Mustache-based templates which you can override (Hello from OpenAPI Generator | OpenAPI Generator). By using the -t option with a folder of modified templates or by using the openapi-generator-cli meta command to scaffold a new generator, you can tailor the output to your needs. This is an advanced feature, and the default templates are usually sufficient for most use cases.

  Using the Generated SDK (OpenAPI Generator)

  The output will typically include a README with usage instructions. Generally, you will need to build or install the generated SDK into your project:

  • For many languages (Java, PHP, C#), the generator produces a project (e.g. Maven pom.xml for Java, a .csproj for C#). You can open or build that project to produce a library artifact (jar, dll, etc.).

  • For Python, it creates a package (often with setup.py or pyproject.toml). You can install it with pip install /path/to/output/package or use it directly by adding to your PYTHONPATH.

  • For JavaScript/TypeScript, it might produce an NPM package (with package.json). You can run npm install in the output directory or even publish it to a registry for reuse.

  After installing the SDK, you can import it in your code. The exact usage varies by language, but typically you initialize a configuration or API client object, set the base URL (if not already set) and authentication credentials, then call API methods. For example, in a TypeScript client generated by OpenAPI Generator (using typescript-fetch template), you might do:

  import { DefaultApi, Configuration } from 'my-api-client';
  const config = new Configuration({ 
    basePath: 'https://api.example.com',
    apiKey: 'YOUR_API_KEY'  // or other auth setup
  });
  const client = new DefaultApi(config);
  const result = await client.getPets();  // calling an endpoint method
  

  In this example (hypothetical), DefaultApi contains methods corresponding to API operations, and we pass a Configuration with the base path and API key (OpenAPI Generator - typescript - How to set API key? - Stack Overflow). Other generators have similar patterns: e.g. a ApiClient class in Python where you set api_key, or a Configuration object in Java.

  Swagger Codegen (V3)

  Overview and Supported Languages

  Swagger Codegen is the original code generation tool released by SmartBear (the company behind Swagger/OpenAPI). It can generate client SDKs in over 40 languages and server stubs in 20+ languages ( API Code & Client Generator | Swagger Codegen ). Languages supported largely overlap with OpenAPI Generator, though OpenAPI Generator (as a fork) has extended and newer generators. Swagger Codegen v3 supports OpenAPI 3.0 and 2.0 specs, and it remains open-source on GitHub. It is backed by SmartBear, which also integrates it into their SwaggerHub platform for easy one-click SDK downloads (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |). However, Swagger Codegen’s open-source project sees slower updates – the latest version as of early 2021 was 3.0.25 (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |). (In practice, many users have migrated to OpenAPI Generator for community enhancements, but Swagger Codegen is still perfectly usable for many scenarios.)

  Installation

  Swagger Codegen is a Java-based tool. Common installation options:

  • Homebrew (macOS/Linux): brew install swagger-codegen will install the latest Swagger Codegen CLI via Homebrew (swagger-codegen/docs/building.md at master · swagger-api/swagger-codegen · GitHub).

  • Executable JAR: Download the swagger-codegen-cli.jar (v3) from the Swagger Codegen GitHub releases. You’ll need Java (JRE 8 or above) to run it.

  • Docker: SmartBear provides Docker images (swaggerapi/swagger-codegen-cli-v3) which can be used similarly to OpenAPI Generator’s images.

  • Source/Maven: You can build from source with Maven if needed, but this is rarely necessary for consumers.

  Prerequisites: If running via JAR, ensure Java is installed. For v3, Java 8+ and Maven 3.3.3+ are recommended (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |). On Windows, installing wget or using PowerShell’s Invoke-WebRequest is needed to download specs in CLI examples (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |).

  Generating an SDK with Swagger Codegen

  Using Swagger Codegen’s CLI is similar to OpenAPI Generator. The main command is swagger-codegen generate with -i, -l (note: Swagger Codegen uses -l for language, whereas OpenAPI Generator uses -g), and -o. For example, using the Homebrew-installed swagger-codegen command:

  swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/ ([swagger-codegen/docs/building.md at master · swagger-api/swagger-codegen · GitHub](https://github.com/swagger-api/swagger-codegen/blob/master/docs/building.md#:~:text=To%20install%2C%20run%20,codegen))
  

  This command fetches the Petstore example OpenAPI and generates a Ruby client SDK to /tmp/test/ using the built-in Ruby templates. You can replace the -l value with any supported language (e.g. java, python, typescript-angular, csharp, etc.). If using the JAR directly, include the path to the jar: java -jar swagger-codegen-cli.jar generate -i openapi.json -l python -o ./python_sdk (swagger-codegen/README.md at 3.0.0 · paveI-fando/swagger-codegen · GitHub).

  Just like OpenAPI Generator, Swagger Codegen allows additional options via -c (config file) or -D (system properties). The set of options may differ slightly; you can run swagger-codegen-cli config-help -l <language> to see available config parameters for a given generator (swagger-codegen/README.md at 3.0.0 · paveI-fando/swagger-codegen · GitHub).

  Templates and Customization

  Swagger Codegen uses Handlebars/Mustache templates under the hood (the v3 uses Mustache, similar to OpenAPI Generator). You can customize templates by supplying your own directory with the -t option. For example, you could adjust how the SDK classes are generated by copying the default templates from the Swagger Codegen GitHub, modifying them, and pointing the CLI to use those. Swagger Codegen v3’s template engine (jmustache) allows altering the generated code’s syntax/style (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |). This is an advanced use case; for most needs, the default templates produce standard, idiomatic code for each language.

  Using the Generated SDK (Swagger Codegen)

  Once Swagger Codegen generates the SDK code, the usage is essentially the same as with OpenAPI Generator (since the output structures are very similar). You will typically:

  • Build or install the generated library. For example, if you generated a Java client, run mvn install in the output (if a pom.xml is provided) to install it to your local Maven repository. For a JavaScript client, run npm install in the output to install dependencies.

  • Add the generated library as a dependency in your application, or directly include the source files.

  • Configure authentication: The generated code will have placeholders or configuration classes for auth. For instance, if your OpenAPI spec uses API key auth, the SDK might have a configuration method or API client property to set the API key (e.g., apiClient.configuration.apiKey = 'YOUR_KEY'). OAuth2 or Bearer tokens are handled similarly by setting an access token in configuration.

  • Call API methods: The SDK will expose functions or methods corresponding to each API operation (often organized into classes by tags). For example, apiInstance.getPetById(id) or similar, returning data or using callbacks/promises depending on the language.

  Because Swagger Codegen and OpenAPI Generator share a lineage, their generated SDKs are used in much the same way – focus on instantiating the client with the correct base URL and auth, then use the provided methods. Refer to the README or samples included in the output for specifics on method names and usage.

  Azure AutoRest

  Overview and Supported Languages

  AutoRest is Microsoft’s OpenAPI code generation tool, well-known for being used to produce Azure SDKs. It’s an open-source project with a large number of contributors (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |). AutoRest supports multiple languages out-of-the-box, including C#, Go, Java, JavaScript/TypeScript (Node), Python, Ruby, and PowerShell (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |) (Generating Clients with AutoRest | autorest). It focuses on creating high-quality, idiomatic client libraries, and is geared toward cloud SDK scenarios (it can even produce Azure-specific variants of SDKs for Azure services). AutoRest reads an OpenAPI 2.0 or 3.0 spec and generates a strongly-typed client in the target language, handling the boilerplate of HTTP calls, parameter serialization, and authentication. It’s designed to prevent developers from having to handcraft API calls for multiple languages (3 Tools to Auto-Generate Client Libraries From OAS | Nordic APIs |).

  Key features of AutoRest include the ability to use configuration files to drive generation (allowing you to specify settings and even combine multiple OpenAPI specs), and a plugin architecture for language generators. It’s worth noting that AutoRest is often used via CI pipelines to regenerate SDKs automatically when API specs change.

  Installation

  AutoRest is distributed as an npm package (written in TypeScript). To install, you need Node.js (LTS version recommended). Then run:

  npm install -g autorest ([autorest/docs/install/readme.md at main · Azure/autorest · GitHub](https://github.com/Azure/autorest/blob/main/docs/install/readme.md#:~:text=2.%20Install%20AutoRest%20using%20))
  

  This installs the autorest CLI globally. Verify by running autorest --version (AutoRest v3 is the current major version (autorest/docs/install/readme.md at main · Azure/autorest · GitHub)). AutoRest may also download specific language generator plugins on first use (it will do this automatically when generating code).

  Note: On Windows, you can also install AutoRest via Chocolatey (choco install autorest) or use it as a .NET Core global tool, but the npm method is the most straightforward and works cross-platform.

  Generating an SDK with AutoRest

  AutoRest can be driven entirely via command-line flags or via a configuration file. The simplest usage is to pass the input spec and the desired language directly as flags. For example, to generate a Python client:

  autorest --input-file=pets.json --python --output-folder=./python_sdk ([Generating Clients with AutoRest | autorest](http://azure.github.io/autorest/generate/#:~:text=We%20also%20need%20to%20tell,our%20command%20line%2C%20we%20get))
  

  In this command, --input-file=pets.json specifies the OpenAPI file, --python selects the Python generator, and --output-folder chooses the destination directory. Similarly, you could use --csharp for a C# SDK, --java for Java, --go for Go, etc. AutoRest’s CLI uses flags like --csharp rather than a generic -g flag (Generating Clients with AutoRest | autorest).

  For more complex projects, you can create a configuration YAML (commonly named readme.md or .autorest.yaml) where you can specify multiple input files, adjust settings, and even generate multiple language SDKs in one go. Then you simply run autorest <config-file> (Generating Clients with AutoRest | autorest). This is powerful for large APIs or when automating generation for several languages at once.

  AutoRest offers various options such as --namespace (for setting the namespace/package name) (Generating Clients with AutoRest | autorest), --add-credential (to include an authentication credential requirement in the client) (Generating Clients with AutoRest | autorest), and flags to toggle certain features. You can consult AutoRest’s documentation for language-specific options.

  Example: Generating a C# client library might look like:

  autorest --input-file=openapi.yaml --csharp --namespace=My.Api.Client --output-folder=./csharp_sdk
  

  This would create a C# .NET Standard project under ./csharp_sdk with a namespace My.Api.Client for the generated classes.

  Using the Generated SDK (AutoRest)

  AutoRest-generated SDKs are designed to be high-quality and idiomatic. For instance, a C# SDK will consist of one or more classes (often a client class and model classes) that you can directly integrate into your .NET application. A Python SDK will be a Python package you can install (AutoRest for Python generates a setup.py by default, so you can do pip install . in the output directory to install it).

  Common steps after generation:

  • Add to Project: If it's C#, add the .csproj to your solution or reference the built DLL. For Java, publish the JAR to your local maven repository or include the sources. For Python/JS, use pip or npm as mentioned.

  • Authentication: AutoRest often generates code that supports dependency injection of credentials. For example, in Azure SDKs (which use AutoRest), the client constructor may take a credential object (like a TokenCredential). If you used the --add-credential flag for a generic API, the client will expect some form of auth token or key to be provided on initialization (Generating Clients with AutoRest | autorest). You will need to consult the generated code or docs – usually there will be a config class or constructor parameter for auth (e.g. an API key, bearer token, etc.).

  • Calling APIs: Using the SDK is straightforward – create an instance of the main API client class (providing base URL if needed and credentials), then call the available methods. For example, a JavaScript SDK might have usage like:

    const client = new MyApiClient({ baseUri: "https://api.example.com", credentials: ... });
    const result = await client.getPets();
    

    A Python example might be:

    client = MyApiClient(base_url="https://api.example.com", access_token="TOKEN")
    pets = client.get_pets()
    

    (The actual method names and auth patterns depend on the spec’s definitions of security schemes.)

  • Error Handling: AutoRest clients typically throw exceptions or return error objects on API errors. Check the documentation or the code itself (which often includes docstrings or XML comments).

  AutoRest is used for many production SDKs (especially Azure’s), so the generated code is usually production-ready. Ensure you handle paging or long-running operations if your API uses them (AutoRest may provide helper methods or you'll need to manage continuation tokens manually, depending on the spec).

  NSwag

  Overview

  NSwag is a Swagger/OpenAPI toolchain primarily for .NET and TypeScript client generation (GitHub - RicoSuter/NSwag: The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.). It is written in C# and integrates deeply with the .NET ecosystem. NSwag can generate C# client classes (for .NET Standard / .NET Core) and TypeScript clients (suitable for Angular, React, or other TS/JS frameworks) from an OpenAPI definition (GitHub - RicoSuter/NSwag: The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.). It effectively combines what Swagger Codegen or OpenAPI Generator would do for those languages with additional convenience for .NET developers. NSwag is often used in ASP.NET projects to generate a TypeScript client for a web frontend or to generate a C# client for a third-party API.

  Aside from the CLI, NSwag also provides NSwagStudio (a Windows GUI) and can be used as a NuGet/MSBuild package to automate codegen as part of build processes (GitHub - RicoSuter/NSwag: The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.). This makes it very popular in enterprise .NET environments. While its language support is narrower (focused on C# and TypeScript), it provides fine-tuned control for those languages, including support for different HTTP libraries in C#, and multiple TypeScript template variations (Fetch API, Axios, jQuery, Angular-specific services, etc.).

  Installation

  NSwag offers multiple installation methods:

  • NuGet (.NET Global Tool): You can install the NSwag CLI as a .NET Core global tool: dotnet tool install -g NSwag.ConsoleCore. After installation, use the nswag command.

  • NPM (Node.js): NSwag is also packaged on npm. For example: npm install -g nswag will install it globally (nswag - npm). (Note: this still requires .NET Core runtime on your system (nswag - npm), since the npm package wraps the .NET binaries.)

  • Chocolatey (Windows): choco install nswagstudio will install NSwagStudio (which includes the CLI).

  • Download Binary: You can download the NSwag command-line binaries from the NSwag GitHub releases if needed.

  After installation, verify by running nswag help. Using NPM or the .NET tool will output a help listing of available subcommands (for example, nswag help aspnetcore2openapi or nswag help openapi2csclient).

  Generating an SDK with NSwag

  NSwag can generate code either via command line arguments or via a configuration JSON file (.nswag file). The easiest way to use it for one-off generation is with direct commands. NSwag’s CLI has specific commands for each generation task:

  • openapi2csclient – Generate C# client code from an OpenAPI spec (CommandLine · RicoSuter/NSwag Wiki · GitHub) (CommandLine · RicoSuter/NSwag Wiki · GitHub).

  • openapi2tsclient – Generate TypeScript client code from an OpenAPI spec (CommandLine · RicoSuter/NSwag Wiki · GitHub).

  • (It also has commands to generate C# controllers or to generate specs from code, but those are out of scope here.)

  For example, to generate a C# client library from openapi.json:

  nswag openapi2csclient /input:openapi.json /output:ApiClient.cs /namespace:My.Api.Client ([CommandLine · RicoSuter/NSwag Wiki · GitHub](https://github.com/RicoSuter/NSwag/wiki/CommandLine#:~:text=nswag%20openapi2csclient%20%2Finput%3AMyWebService,cs))
  

  This will produce a single C# file ApiClient.cs with classes to call the API (you can also split into multiple files via options if desired). You can specify /namespace: for the C# namespace of the client classes. Similarly, to generate a TypeScript client:

  nswag openapi2tsclient /input:openapi.json /output:apiClient.ts /template:Fetch
  

  This would create apiClient.ts using the Fetch API template. NSwag supports templates like Fetch (fetch API), Axios, Angular, etc., and you can specify additional settings like module generation, promise vs callback style, etc., either via command options or a config file.

  Using a Configuration File: NSwag allows you to create a JSON configuration (e.g., nswag.json) that contains all the settings for one or more generations. You can create one by running nswag new (CommandLine · RicoSuter/NSwag Wiki · GitHub), then editing the file (which is self-documented) to add your input spec and generation options. Once you have the config, run nswag run nswag.json to generate the code according to that config (CommandLine · RicoSuter/NSwag Wiki · GitHub). This approach is good for repeatable builds (you can check the config into source control).

  Using the Generated SDK (NSwag)

  C# Client: The C# output is usually one or a few .cs files that you can include in your project or compile into a library. NSwag’s default C# template generates a partial class for the client and uses HttpClient internally (often with the option to inject your own HttpClient). To use it, you simply instantiate the generated client class, set the BaseUrl (if not already set to the server in the OpenAPI spec), and call the methods corresponding to your API endpoints. For example:

  var client = new MyApiClient("https://api.example.com/"); 
  client.ApiKey = "YOUR_API_KEY";  // if the spec defines an API key security
  var result = await client.GetPetsAsync();
  

  The client class will have properties or methods to set auth tokens or API keys (often NSwag will generate an ApiKey property for API key auth, or a mechanism to inject headers for OAuth). This makes it easy to handle authentication.

  One nice feature: NSwag’s C# generator can utilize modern .NET features. It can generate synchronous and async methods (usually with Async suffix for async). It can also generate Data Transfer Objects (DTO classes for schemas) and even client interfaces if configured.

  TypeScript Client: The TypeScript output could be a single file or multiple files (depending on settings). If you target Angular, NSwag can generate an Angular service class. If using Fetch or Axios, it might generate a standalone API class. Usage in an app involves importing that class or functions, configuring the base URL if needed, and calling methods. For instance, with a Fetch client:

  import { MyApiClient } from './apiClient';
  const client = new MyApiClient(undefined, 'https://api.example.com'); // sometimes first parameter might be httpClient instance, so 'undefined'
  client.apiKey = 'YOUR_API_KEY';
  client.getPets().then(pets => { console.log(pets); });
  

  (Note: The exact usage varies with template, but NSwag typically documents this in a generated README comment at the top of the file.)

  Because NSwag is often run in-process (in .NET apps), you might also see usage where at build time the C# or TS client is regenerated automatically. This ensures the SDK is always up to date with the latest API. If using NSwagStudio, you can interactively configure the generation and preview the output.

  APIMatic

  Overview and Supported Languages

  APIMatic is a commercial platform focused on SDK generation and API developer experience. Unlike the other tools (which are open-source), APIMatic provides a cloud-based service and a CLI that can generate SDKs for over 10 languages from a given API spec ( OpenAPI.Tools - an Open Source list of great tools for OpenAPI. ). It supports most popular languages/frameworks: Java, C# (.NET), Python, TypeScript/Node, PHP, Ruby, Go, Swift, Android (Java/Kotlin), iOS (Objective-C/Swift), and more. APIMatic places an emphasis on creating fully featured SDKs – not just API wrappers, but libraries that include features like input validation, retries, and convenient authentication handlers. It also can generate API documentation portals and code samples, making it a comprehensive solution for companies offering SDKs to third-party developers.

  APIMatic can ingest OpenAPI v2/v3, as well as other formats (RAML, WSDL, Postman collections, etc.), and output client libraries. The APIMatic CLI is essentially a way to use their cloud generation engine from your terminal or CI process.

  Installation of APIMatic CLI

  The APIMatic CLI is built on Node.js and distributed via npm. To install it globally, run:

  npm install -g @apimatic/cli ([Installing APIMatic CLI | APIMatic Documentation](https://docs.apimatic.io/apimatic-cli/intro-and-install/#:~:text=Run%20the%20following%20command%20to,install%20the%20CLI))
  

  After installation, the apimatic command will be available. You may need to authenticate or provide an API key for APIMatic. The first use of certain commands will prompt for an APIMatic API key or ask you to log in (you can obtain an API key by signing up for an APIMatic account). Once configured, the CLI will use your credentials to access the SDK generation service.

  Confirm the installation with apimatic --version or get help with apimatic --help.

  Generating an SDK with APIMatic CLI

  Using APIMatic CLI is straightforward. The CLI communicates with APIMatic’s cloud to generate the SDK and download it to your local machine. The primary command for SDK generation is apimatic sdk:generate. You must specify at least the output language/platform and the input spec file. For example, to generate a Python SDK:

  apimatic sdk:generate --platform=python --file="openapi.json" --zip ([APIMatic CLI Commands | APIMatic Documentation](https://docs.apimatic.io/apimatic-cli/commands/#:~:text=The%20following%20example%20generates%20Python,zip%20file))
  

  Explanation of this example command:

  • --platform=python selects the Python SDK generation. (You could put java, csharp, typescript, php, ruby, etc. here for other languages (APIMatic CLI Commands | APIMatic Documentation).)

  • --file="openapi.json" points to your OpenAPI spec file (local path). You can also provide a URL via a --url parameter if your spec is hosted online.

  • --zip tells APIMatic to package the SDK as a .zip and download it. By default, APIMatic will place files in an output folder, but --zip is convenient to get everything as an archive.

  When you run this, the CLI uploads the spec to APIMatic, generates the SDK on their server, and then downloads the resulting SDK code. You will see progress output like “Generating SDK... done” and “Downloading SDK... done” (APIMatic CLI Commands | APIMatic Documentation), and then a success message with the location of the zip (or files). For instance, “Your SDK is located at D:\sample_sdk_python.zip” (APIMatic CLI Commands | APIMatic Documentation).

  APIMatic’s CLI can also generate directly to a folder (without zipping) if you omit --zip and use --destination=<folder>. You can run apimatic sdk:generate --help to see all options and supported platform codes (APIMatic CLI Commands | APIMatic Documentation).

  In addition to SDK generation, APIMatic CLI has commands to validate or transform API definitions (e.g., apimatic transform to convert between formats), and to generate documentation portals. These can be handy if you need to preprocess your OpenAPI spec (for example, APIMatic can merge multiple files or fix certain inconsistencies).

  Using the Generated SDK (APIMatic)

  The SDKs generated by APIMatic are intended to be consumer-ready. APIMatic typically includes a detailed README and even example code in each generated SDK. General steps:

  • Unpack/Install: If you received a zip, unpack it. The contents usually include source files and project files for the language. For example, a C# SDK zip will contain a Visual Studio solution or .csproj, a Java SDK will have a Gradle/Maven setup, etc. You can open these projects and build them. Alternatively, APIMatic’s README often guides how to install via the language’s package manager:

    • For Java, they may provide a compiled JAR and instructions to add it to your project or install it via Maven local repo.

    • For Python, they usually provide a setup.py; you can do pip install . inside the SDK directory to install it.

    • For Node/TypeScript, there will be a package.json allowing you to do npm install (sometimes the SDK is also published to NPM if you used APIMatic’s integrated publishing).

  • Authentication: APIMatic SDKs often include dedicated methods or configuration for auth. For instance, they might generate an Configuration class where you set API keys or base URLs, or the main client class might have builder methods. For example, in a Java SDK you might see something like MyApiClient client = new MyApiClient.Builder().apiKey("KEY").build();. In a Python SDK, there might be a Configuration module or you pass the API key when initializing the client. These patterns are documented in the generated README.

  • Calling API methods: Once configured, you use the SDK in a straightforward manner: calling methods that correspond to endpoints. E.g., client.get_all_pets() or client.pets.getAll() depending on how the SDK is structured (APIMatic sometimes groups endpoints into controller classes). The naming tries to be user-friendly and consistent.

  One thing to note: APIMatic’s generated code often depends on an APIMatic core library (for example, they have an APIMatic.Core for C# and similar for other languages) which provides common functionality (like HTTP request building, serialization, error handling). You will need to include these dependencies, but the project files usually reference them or the README explains how to get them (often they are hosted on package managers like NuGet, PyPI, etc., so just building the project will fetch them).

  Because APIMatic is a high-level tool, the generated SDKs sometimes include extra features like:

  • Type validation: ensuring inputs match expected types (to help developers catch mistakes).

  • Automatic retries: for certain error codes (if configured).

  • Convenience methods: e.g., handling pagination if the API supports it.

  Using the SDK is meant to feel like using any hand-written library. Just follow the patterns given. Also, if you encounter issues or want to adjust something, APIMatic allows some customization of the generation via their web interface (for example, you can rename certain classes or adjust the data models if the spec isn’t ideal). But that’s outside the pure CLI usage.

  Using the Generated SDKs in Your Project

  Once you have generated an SDK with one of the tools above, here are some general guidelines for integrating and using it:

  1. Add the SDK to Your Project

  Depending on the language, you might do one of the following:

  • Install via Package Manager: If the SDK is packaged (or you package it yourself), you can publish it to a repository (Maven, npm, PyPI, NuGet, etc.) and then import it like any other dependency. Some tools (OpenAPI Generator, Swagger Codegen) include configuration for publishing. For a quick local use, you can often use a local file reference (e.g., pip install /path/to/sdk, or npm install ../path/to/sdk).

  • Include Source Directly: You can copy the generated source files into your project. For example, drop the generated .cs files into your .NET project or include the .java files in your Java project’s source. This is simple, though managing updates might be harder than if it were a separate library.

  • Library Project Reference: Treat the SDK as a separate library in your solution. For instance, you might generate a Java SDK, build it into a JAR, and then include that JAR in your main app. Or for .NET, add the generated client project to your solution and add a project reference.

  Make sure to also include any dependencies the SDK requires. Generated SDKs often rely on standard libraries (e.g., Guzzle for PHP HTTP, Axios or Fetch API for TS, requests for Python, System.Net.Http for C#). These should be listed in a generated project file or README.

  2. Configure the SDK (Base URL, Authentication)

  Most SDKs require you to specify the API’s base URL (unless the OpenAPI spec had a default server) and any authentication details:

  • Base URL: Typically, the generator will use the first server URL in the OpenAPI file as the default. If your API has multiple environments or you need to override it, look for a configuration property. For example, OpenAPI Generator’s Python client has a Configuration.host you can set, and its TypeScript fetch client accepts a basePath (OpenAPI Generator - typescript - How to set API key? - Stack Overflow). Swagger Codegen’s clients similarly have a base URL field. In Autorest, the base URL is usually set in the generated client constructor (passed as a parameter).

  • Authentication: This depends on the auth schemes defined in your OpenAPI spec:

    • API Keys: The SDK will have a property or setter for the API key. It might be named after the security scheme. For instance, if your security scheme is ApiKeyAuth in the OpenAPI, OpenAPI Generator’s TypeScript might expect configuration.apiKey for that scheme (OpenAPI Generator - typescript - How to set API key? - Stack Overflow), or a dictionary of credentials with the scheme name (OpenAPI Generator - typescript - How to set API key? - Stack Overflow). In C# or Java, there might be an ApiKeyAuth class or simply a config field.

    • HTTP Bearer/Auth (OAuth2): The SDK may require a token to be set. Often there's a accessToken or BearerToken field to populate, or a function to supply a token (some generators allow you to set an Authorization header through config).

    • HTTP Basic: The SDK might have you set Username and Password fields in config.

    • Custom: Some generators might not fully implement complex OAuth flows; you might need to manually handle token acquisition and just set the bearer token.

    Each tool’s output will document this. For example, AutoRest’s documentation for generated clients explains how to authenticate for each language (Azure clients use credential objects) (Generating Clients with AutoRest | autorest). OpenAPI Generator often includes comments in the code about where to set API keys or tokens.

  • Other Config: Some SDKs allow configuration of timeouts, retries, logging. For example, APIMatic’s SDKs often come with configurable retry logic. Check the README or config class.

  3. Call API Methods

  With config done, you can now call the methods provided by the SDK:

  • The methods are typically named after your operations (often based on the operationId in the OpenAPI spec, or derived from the path). For instance, an operation GET /pets might become getPets() method in the SDK.

  • Some SDKs group methods by tags or resource. For example, AutoRest might create a client class per tag, or OpenAPI Generator might put them all in one class (depending on language). So you might have to instantiate a specific service class, e.g. PetApi or use a single DefaultApi.

  • The methods will usually return the response data in a native type (e.g. a model class or a primitive type). If the API returns JSON objects, the generator creates model classes for those schemas. For example, a Pet object in OpenAPI becomes a Pet class in most languages, so getPets() might return a list/array of Pet instances. In dynamic languages, it might return a dict or just parsed JSON.

  • Error handling: If an API call returns an error HTTP code, the SDK might throw an exception (like ApiException) or return an error object. Consult the generated documentation. Generally, be prepared to catch exceptions for non-2xx responses.

  Example: Using a generated Python SDK (OpenAPI Generator):

  from my_sdk import ApiClient, Configuration, DefaultApi
  
  config = Configuration(host="https://api.example.com", api_key={"ApiKeyAuth": "ABC123"})  # Setup config ([OpenAPI Generator - typescript - How to set API key? - Stack Overflow](https://stackoverflow.com/questions/76726805/openapi-generator-typescript-how-to-set-api-key#:~:text=This%20is%20how%20you%20do,fetch%20generator))
  client = ApiClient(configuration=config)
  api = DefaultApi(api_client=client)
  try:
      pets = api.get_pets()  # invokes GET /pets
      print(pets)
  except my_sdk.ApiException as e:
      print("API error:", e)
  

  In this snippet, we configured the base host and an API key for a scheme named ApiKeyAuth (OpenAPI Generator - typescript - How to set API key? - Stack Overflow), then called get_pets() and handled a potential exception.

  4. Maintain and Regenerate as Needed

  APIs evolve, so your OpenAPI spec may get updated over time. It’s good practice to regenerate the SDK whenever the API changes (new endpoints, schema changes, etc.). Because the generation process is automated, you can integrate it into your CI/CD pipeline or release process. For example, you might have a script that runs OpenAPI Generator or AutoRest to update the SDK, and then your application can pull in the new version.

  If you have customized the generated code manually, be cautious – regenerating will overwrite those changes. Instead, try to use the tools’ customization features (templates, configuration options) to adjust output, so you can always re-run generation without losing important tweaks.

  5. Testing the SDK

  After generation, it’s wise to test a few calls to ensure the SDK works as expected with your live API. Most generators create correct code if the OpenAPI spec accurately describes the API. If you find any issues (e.g., an operation not working), it could indicate the spec might be incomplete or the generator had a bug with a certain edge case. In such cases, you might need to adjust the spec or use a different tool/template. That said, the tools covered are well-supported and generally reliable.