OpenAPI 3.0 - Overriding Code-Generation Templates

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:

The resulting generated code looks like this:

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

• The operation does have query parameters (In contrast to e.g. path parameters. For definition see: https://swagger.io/docs/specification/describing-parameters/)
• AND at least one of the queryParameters serialization-parameters are style = form, explode= true  (this was called collectionFormat=multi in openApi 2.0) which is the default for all queryParameters. For details see https://swagger.io/docs/specification/serialization/
• AND the parameter is an array

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’:

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:

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

So the following default values apply:

• OpenAPI-Specification/3.0.1.md at main · OAI/OpenAPI-Specification

• https://swagger.io/docs/specification/serialization/

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.

‍