How to Generate Clients for PTV Developer APIs

In this tutorial you will learn how to generate clients for PTV Developer APIs. 

The API specification of each PTV Developer API is available as OpenAPI document of version 3 in JSON format. Each API documentation contains a download link for its specification on the API Reference page. The big advantage of an OpenAPI document is that it can be used as a basis for different tools to generate client classes in various languages. Using client classes makes it easier and more convenient to integrate the API into an existing programming environment. Currently, we recommend to use OpenAPI Generator in version 7.5.0 or newer. Please note that OpenAPI Generator needs a Java runtime installation (at least Java 8).

If you don't want to generate the clients yourself, you can find clients for Java, C# and TypeScript ready to download on GitHub.

In the following chapters we describe how to generate clients with different tools using the Routing API as example. This table shows which tool can be used to generate clients in which language:

NPM

• Put the API specification of PTV Developer Routing API as file openapi.json into the subdirectory routing of your working directory.
• Put these scripts as file package.json into your working directory:

{
  "name": "@ptvgroup/developer-api-clients",
  "version": "1.0.0",
  "scripts": {
    "generate-dotnet": "openapi-generator-cli generate --generator-name csharp --additional-properties=targetFramework=net8.0,useDateTimeOffset=true,optionalEmitDefaultValues=false --global-property apis,apiTests=false,models,modelTests=false,supportingFiles",
    "generate-typescript": "openapi-generator-cli generate --generator-name typescript-fetch --additional-properties=typescriptThreePlus=true --global-property apis,apiTests=false,models,modelTests=false,supportingFiles",
    "generate-java": "openapi-generator-cli generate --generator-name java --additional-properties=java8=true,dateLibrary=java8,library=native --global-property apis,apiTests=false,models,modelTests=false,supportingFiles --type-mappings=AnyType=Object"
  },
  "devDependencies": {
    "@openapitools/openapi-generator-cli": "^2.15.3"
  }
}

• Execute the following command in your working directory:

npm install @openapitools/openapi-generator-cli

• Execute one of these commands in your working directory to generate the client classes for the target language of your choice:

npm run generate-dotnet -- --input-spec ./routing/openapi.json --output ./routing/dotnet-client --additional-properties=packageName=PTVGroup.Developer.Clients.Routing --openapi-normalizer SET_PRIMITIVE_TYPES_TO_NULLABLE='\"integer|number|string|boolean|dateTime\"'
npm run generate-typescript -- --input-spec ./routing/openapi.json --output ./routing/typescript-client
npm run generate-java -- --input-spec ./routing/openapi.json --output ./routing/java-client --additional-properties=apiPackage=com.ptvgroup.developer.client.routing.api,modelPackage=com.ptvgroup.developer.client.routing.model,invokerPackage=com.ptvgroup.developer.client.routing

Maven 3

The following steps describe how to generate clients of the PTV Developer Routing API as an example using Maven 3.3.4 or above: Create a Maven 3 project and put the API specification of PTV Developer Routing API as file openapi.json into the subdirectory src/main/resources/routing of your project. Add this plugin execution to the plugins section of your POM and build it with Maven using mvn install:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.9.0</version>
    <executions>
        <execution>
            <id>java-client</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>generate-sources</phase>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/routing/openapi.json</inputSpec>
                <output>${project.build.directory}/java-client/routing</output>
                <generatorName>java</generatorName>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <typeMappings>AnyType=Object</typeMappings>
                <configOptions>
                    <java8>true</java8>
                    <dateLibrary>java8</dateLibrary>
                    <library>native</library>
                    <invokerPackage>com.ptvgroup.developer.client.routing</invokerPackage>
                    <apiPackage>com.ptvgroup.developer.client.routing.api</apiPackage>
                    <modelPackage>com.ptvgroup.developer.client.routing.model</modelPackage>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

For the initial generation the compilation will fail because of missing dependencies. For successful compilation, copy all dependencies of default scope from the POM in directory target/java-client/routing to your project POM or use the generated Maven project as a whole for further development.

VisualStudio

To generate C# clients using Microsoft Visual Studio first install an extension for client generation with OpenAPI Generator. 
Go to Extensions -> Manage Extensions and search for REST API Client Code Generator.

Download the extension and restart Visual Studio to install it.

Go to Tools -> Options -> REST API Client Code Generator -> OpenAPI Generator and set Emit Default Value to false.

Right click your project and add the API Client via Add -> New REST API Client -> Generate with OpenAPI Generator.

Enter the URL to the API specification.

The following code snippet shows how to use the newly generated C# clients.

using ClientGeneration.Api;
using ClientGeneration.Client;
using ClientGeneration.Model;
using System.Collections.Generic;

namespace ClientGeneration
{
    class Program
    {
        static void Main(string[] args)
        {
            var apiKey = new Dictionary<string, string> {
                { "apiKey", "YOUR_API_KEY" }
            };

            Configuration configuration = new Configuration();
            configuration.ApiKey = apiKey;

            RoutingApi routing = new RoutingApi(configuration);

            List<string> waypoints = new List<string> { "49.0133618,8.4277972", "48.8950289,8.6715602" };
            List<Results> results = new List<Results> { Results.POLYLINE, Results.WAYPOINT_EVENTS };

            RouteResponse response = routing.CalculateRoute(waypoints, results: results);
        }
    }
}