Tech Story

OpenAPI 3.0 - Overriding Code-Generation Templates

07.10.2022
·   Lesedauer:
5 Minutes

OpenAPI 3.0 - Overriding Code-Generation Templates

Initial situation

In the accounting-service-project we use openapi-generator-cli to generate source code for accessing the finapi. We use the typescript-nestjs-generator which is considered ‘experimental’. We encountered a situation where generating the code for the finapi-access-service produces code that does not compile giving errors (at 80 different spots) in the following form:

Code Error

The resulting generated code looks like this:

Generated Code

The problem is that queryParameters does not have an append function. This problem only arises when

Therefore the former dev-team  changed all occurrences of line 3 to

let queryParameters = new URLSearchParams();

and then committed the generated code.

This change makes the code compile. It is still possible though, that the parameters added by addParams are not sent to server since the further code might not explicitly handle an URLSearchParam and instead just looks at the properties of the object.

Overriding the code generation template

In order to generate code that compiles, and in order to remove the generated code from git, we can customize the way openapi-generator-cli generates code.

OpenAPI Generator · Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents )

The typescript-nestjs-generator uses moustache-template files. First we need to to extract the template files which are currently used by the typescript-nestjs-generator.

yarn openapi-generator-cli author template -g typescript-nestjs

The files are written to a newly created folder ‘out’ Then we change the file ‘api-service.moustache’:

Generated file

Then we create a new folder called custom-template and copy the modified .moustache-file to it.

When generating code we need to pass the new template folder:

yarn openapi-generator-cli generate -g typescript-nestjs -o generated_sources/finapi/access-service  -i resources/finapi/openapi-access-latest.yaml --additional-properties=supportsES6=true -t ./openapi-customtemplate

Now the generated code compiles again.🕺🏽

Possible upcoming problems and approaches

Possibly missing handling of multi-parameters

  • As stated before, although the code does compile, it still might be that the generated code does not correctly take Array-QueryParamters into account. In this case it might be helpful to take a look into the templates of similar (but not experimental) generators like typescript-axis or typescript-node. Maybe it makes sense to switch to a non experimental generator and create the boilerplate-code for using as  a nest-service by ourselves.

Discrepancy in finapi-access-API

There seems to be a discrepancy between the formal description of the finapi-access-api

  • in https://sandbox.finapi.io/api-docs/openapi-access-latest.yaml
  • and the prosaic description in finAPI API Documentation

The API-Documentation for example for deleteAllAccounts states, that the accountIds are passed as csv:

API-Docu

The definition in the yaml-file however does not explicitly state any serialization-parameters.

Yaml-File

So the following default values apply:

Open-API specification

So instead of single parameter with comma separated values, there should be parameter for each value. If this discrepancy turns out to be a problem (and its not just that the prosaic description is wrong) then a solution could be to add  ‘explode=false’ to all properties in the openapi-access-latest.yaml.

Ein Artikel von

Daniel Brammertz

Head of Development

Daniel bringt rund 20 Jahre Erfahrung im Bereich IT mit. In den letzten 10 Jahren war er selbst CTO in seinem eigenen CRM-Software Unternehmen. Bei SCALARA hält der studierte Informatiker nun alle Fäden in der Softwareentwicklung zusammen und ist Sparringpartner von unserem CTO Alex. Daniel ist erster Ansprechpartner für das Entwicklerteam ist für den Aufbau der weiteren Teams zuständig und brennt für neue Technologien.

Zur Artikel Übersicht