This specification supports the latest version of the Onfido API (v3.6).
It can also be used for generating client libraries to allow backend services to interact with the Onfido API. A Postman collection is provided as well for user's convenience.
Client libraries are built by Onfido in 5 different programming languages.
Nevertheless, users can generate libraries in any other language supported by the OpenAPI Generator.
The libraries below are generated and maintained by Onfido:
Libraries come with Webhook Events validation and the possibility to easily choose a region to target.
Please find more information regarding how to use each library within their own README.md file.
Please find in OpenAPI Generator documentation how to build client libraries and all the supported programming languages to build client libraries.
The file openapi.yaml should be provided to the generator.
We recommend providing the generator with the options below (whenever available):
enumUnknownDefaultCase: true
useOneOfDiscriminatorLookup: true
legacyDiscriminatorBehavior: false
disallowAdditionalPropertiesIfNotPresent: false
The openapi-reference/openapi.json file can be used to explore the OpenAPI definition with tools like Swagger Editor or Postman.
A pre-compiled Postman collection is also available in the Onfido documentation portal.
Most of the contents in client libraries are auto-generated using OpenAPI Generator.
Generation is controlled by configuration and template files stored in each generator's folder.
A few exceptions come from a global exclusion list (defined as part of the rsync command in github workflow and sync-lib.sh script):
/.git*
/CHANGELOG*
/.openapi-generator-ignore
/.openapi-generator/FILES
For each generator, additional exclusions are defined into specific exclusions.txt files stored in each generator's folder.
Code is automatically generated into the generated/artifacts subfolders and pushed to each client library repository via automatically generated PRs. Every path matching the exclusion lists defined above is neither copied from artifact folder nor removed from the target client library repository: that’s the way for avoid pushing some contents to client libraries but also avoiding some files (tests and git files) from being removed or overridden.
A few files are automatically generated and committed in the generated/artifacts folder at PR merge time.
Configuration files are named config.yaml and allow for the provision of custom parameters to each generator. Most parameters are defined in the OpenAPI generator documentation. A global configuration (common/config.yaml) is used to store common parameters and share them among the different generators. Configuration files also include some variables (e.g. ${GENERATOR_NAME}) which are replaced before being provided to the Openapi generator (see envsubst
command in generate.sh).
Templates are provided to add particular features to client libraries:
- Webhook Events validation
- Region selection
- Token provisioning
- Customisation of README.md files
- Access to common/custom report sections (when needed)
- Additional libraries for testing (when needed)
In nearly all cases, with the exception of Webhook Event Validation and README.md templates, mustache comments ({{!...}} ) are used to denote modified sections in templates.
To update the OpenAPI generator version, bump the version in both update-specs-and-client-libraries.yaml and generate.sh. Afterwards run the ./shell/generate.sh
script as usual, some errors like below might be raised:
!!! Error while building generator ...!!!
SHA256SUM for template ... changed, diff reported below. To overwrite template, run:
...
This happens when templates we're overriding have been updated. The script automatically fixes checksums for one generator at each run, but the templates need to be carefully reviewed and updated by following the procedure below:
- Check which files have changed, by running
git diff generators/**/templates/SHA256SUM
- Compare each file with the one that has been freshly generated, e.g. if libraries/okhttp-gson/ApiClient.mustache checksum has been denoted as modified for java/okhttp-gson generator:
diff generators/java/okhttp-gson/templates/libraries/okhttp-gson/ApiClient.mustache generated/templates/java/okhttp-gson/libraries/okhttp-gson/ApiClient.mustache
- Add all changes from the new version except the ones noted by mustache comments (i.e.
{{! }}
) - Commit changes to both templates and SHA256SUM files
The changes to README.md should be carefully reviewed by comparing generated/templates/**/README.mustache
files created with different OpenAPI generator versions.
Repository is open to external contributions. At this end please:
-
Fork repository
-
Create your feature branch (
git checkout -b my-new-feature
) -
Make your changes, see below sections for project setup and testing.
-
To update one (or more) client libraries, clone them in the parent folder so that all the onfido-* repositories lie at the same level. Then run the script
./shell/generate.sh
in the onfido-openapi-spec folder and./shell/sync-lib.sh
in each of the client libraries' folder, as in the examples below:../onfido-openapi-spec/shell/sync-lib.sh java java/okhttp-gson ../onfido-openapi-spec/shell/sync-lib.sh php
-
To verify changes to the OpenAPI definition with external tools, run:
./shell/refresh-openapi-spec-for-documentation.py \ generated/artifacts/openapi/openapi.json \ generated/artifacts/openapi-documentation/openapi.json
-
Before committing your changes, run the script
./shell/run-prettier.sh
-
Commit your changes (
git commit -am 'Add some feature'
) -
Push to the branch (
git push origin my-new-feature
) -
Create a new Pull Request
Described below is the procedure on how to deliver new client libraries:
-
Merge all the requested PRs in onfido-openapi-spec.
-
Manually trigger an update-specs-and-client-libraries by clicking over the Run workflow button
-
Select the type of change:
Type Description No change no change expected to client library code Patch bug fix not causing any change to client library interface Minor backward compatible change to client library interface (e.g. new endpoint, new optional parameters) Major non-backward compatible change to client library interface (e.g. remove or change endpoint, new mandatory parameters) -
Select the libraries to update
-
A new PR will be created for each library (or overridden if already present)
-
Update CHANGELOG files adding the new changes just below the new release number
-
Update tests if needed and merge each client-library PR
-
Ship a releases for each client library by:
- setting tag and release name to v0.0.0 (replace 0.0.0 with the actual version)
- using same contents from the CHANGELOG as release description
- making sure Set as the latest release is enabled
- clicking on the Publish release button
-
Update documentation with new client libraries version