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. Please note that OpenAPI Generator needs a Java runtime installation (at least Java 8).

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:

ToolJavaC#TypeScript
NPM
Maven 3
VisualStudio 2019

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-netcore --additional-properties=targetFramework=netcoreapp3.1,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.4.26"
      }
    }      
                            
                        
  • 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
    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>6.0.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 2019

To generate C# clients using Microsoft Visual Studio right click your soultion and add a new service reference.

Select openAPI and either enter the URL to the openapi.json or add it from a local file. Configure a namespace and a name for your client class.