Update README files (including templated ones)

README.md

@@ -1,10 +1,10 @@
-# Onfido OpenAPI specification
+# Onfido OpenAPI Specification
 
 ## Introduction
 
 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](#api-documentation) is provided as well for user's convenience.
+It can also be used for generating client libraries to allow backend services to interact with the Onfido API. Additionally, a [Postman collection](#api-documentation) is provided for user convenience.
 
 ## Client libraries
 
@@ -22,15 +22,15 @@ The libraries below are generated and maintained by Onfido:
 - [onfido-python](https://github.com/onfido/onfido-python)
 - [onfido-ruby](https://github.com/onfido/onfido-ruby)
 
-Libraries come with Webhook Events validation and the possibility to easily choose a region to target.
+Libraries come with Webhook Events validation. They also provide 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.
 
 ### How to build client libraries yourself
 
-Please find in [OpenAPI Generator documentation](https://openapi-generator.tech) how to build client libraries and all the supported programming languages to build client libraries.
+Refer to the [OpenAPI Generator documentation](https://openapi-generator.tech) for the list of supported programming languages and instructions on building client libraries.
 
-The file [openapi.yaml](https://github.com/onfido/onfido-openapi-spec/blob/master/openapi.yaml) should be provided to the generator.
+The file [openapi.yaml](openapi.yaml) should be provided to the generator.
 
 We recommend providing the generator with the options below (whenever available):
 
@@ -51,26 +51,28 @@ A pre-compiled Postman collection is also available in the Onfido [documentation
 
 Most of the contents in client libraries are auto-generated using [OpenAPI Generator](https://openapi-generator.tech).
 
-Generation is controlled by configuration and template files stored in [each generator's folder](https://github.com/onfido/onfido-openapi-spec/tree/master/generators).
+Generation is controlled by configuration and template files stored in [each generator's folder](generators).
 
 ### Exclusion lists
 
-A few exceptions come from a global exclusion list (defined as part of the rsync command in [github workflow](https://github.com/onfido/onfido-openapi-spec/blob/master/.github/workflows/update-specs-and-client-libraries.yaml) and [sync-lib.sh script](https://github.com/onfido/onfido-openapi-spec/blob/master/shell/sync-lib.sh)):
+A few exceptions come from a global exclusion list (defined as part of the rsync command in [sync-lib.sh script](shell/sync-lib.sh)):
 
 - `/.git*`
-- `/CHANGELOG*`
+- `/CHANGELOG.md`
+- `/MIGRATION.md`
+- `/.release.json`
 - `/.openapi-generator-ignore`
 - `/.openapi-generator/FILES`
 
 For each generator, additional exclusions are defined into specific [exclusions.txt files](https://github.com/search?q=repo%3Aonfido%2Fonfido-openapi-spec+path%3A**%2Fexclusions.txt&type=code) stored in each generator's folder.
 
-Code is automatically generated into the [generated/artifacts](https://github.com/onfido/onfido-openapi-spec/tree/master/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.
+Code is automatically generated into the [generated/artifacts](generated/artifacts) subfolders. It is then pushed to each client library repository via automatically generated PRs. Every path matching the exclusion lists defined above is neither copied from the artifact folder nor removed from the target client library repository. This avoids pushing some contents to client libraries and prevents some files (tests and git files) from being removed or overridden.
 
-A few files are automatically generated and committed in the [generated/artifacts](https://github.com/onfido/onfido-openapi-spec/tree/master/generated/artifacts) folder at PR merge time.
+A few files are automatically generated and committed in the [generated/artifacts](generated/artifacts) folder at PR merge time.
 
 ### Configuration files
 
-Configuration files are named [config.yaml](https://github.com/search?q=repo%3Aonfido%2Fonfido-openapi-spec+path%3A**%2Fconfig.yaml&type=code) and allow for the provision of custom parameters to each generator. Most parameters are defined in the [OpenAPI generator documentation](https://openapi-generator.tech/docs/generators/). A global configuration ([common/config.yaml](https://github.com/onfido/onfido-openapi-spec/blob/master/generators/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](https://github.com/onfido/onfido-openapi-spec/blob/master/shell/generate.sh)).
+Configuration files are named [config.yaml](https://github.com/search?q=repo%3Aonfido%2Fonfido-openapi-spec+path%3A**%2Fconfig.yaml&type=code) and allow for the provision of custom parameters to each generator. Most parameters are defined in the [OpenAPI generator documentation](https://openapi-generator.tech/docs/generators/). A global configuration ([common/config.yaml](generators/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](shell/generate.sh)).
 
 ### Templates
 
@@ -106,7 +108,7 @@ This happens when templates we're overriding have been updated. The script autom
 3. Add all changes from the new version except the ones noted by mustache comments (i.e. `{{! }}`)
 4. 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.
+The changes to `README.md` should be carefully reviewed by comparing `generated/templates/**/README.mustache` files created with different OpenAPI generator versions.
 
 ## Contributing
 
@@ -172,7 +174,7 @@ Described below is the procedure on how to deliver new client libraries:
     1. Removing lines that doesn't apply to current library and reference to current language if present
     2. Indenting of two spaces each line and replacing the intial asterix (`*`) with dash (`-`)
     3. Removing `by...` (till the end of the line) for keeping `CHANGELOG.md` file clean
-16. Any additional change manually performed in the library (e.g. updated tests, etc) needs to be added before the _Refresh onfido-..._ line, indented as usual (but using `-` as a list marker to make line appearing in the `CHANGELOG.md` file).
+16. Any additional change manually performed in the library (e.g. updated tests, etc) needs to be added after the _Refresh onfido-..._ block (and any eventual subitem), indented as usual (but using `-` as a list marker to make line appearing in the `CHANGELOG.md` file).
 17. Click on _Publish release_ button
 18. Check that workflows have been succesfully executed (by clicking on the _Action_ button)
 19. Replace `Refresh onfido-...` line in Release notes with the more appropriate `Release based on...` line from `CHANGELOG.md` file

generators/common/templates/README_footer.mustache

@@ -1,36 +1,38 @@
 ## Contributing
 
-This library is automatically generated using [OpenAPI Generator](https://openapi-generator.tech) (version: {{generatorVersion}}); therefore all the contributions, except tests files, should target [Onfido OpenAPI specification repository](https://github.com/onfido/onfido-openapi-spec/tree/master) instead of this repository.
+This library is automatically generated using [OpenAPI Generator](https://openapi-generator.tech) (version: {{ generatorVersion }}); therefore, all contributions (except test files) should target the [Onfido OpenAPI specification repository](https://github.com/onfido/onfido-openapi-spec/tree/master) instead of this repository. Please follow the contribution guidelines provided in the OpenAPI specification repository.
 
 For contributions to the tests instead, please follow the steps below:
 
-1. [Fork](https://github.com/{{ gitUserId }}/{{ gitRepoId }}/fork) repository
+1. Fork the [repository](https://github.com/{{ gitUserId }}/{{ gitRepoId }}/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Make your changes
-4. Commit your changes (`git commit -am 'Add some feature'`)
+4. Commit your changes (`git commit -am 'Add detailed description of the feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
 
 ## Versioning policy
 
-[Semantic Versioning](https://semver.org) policy is used for library versioning, following guidelines and limitations below:
+Versioning helps manage changes and ensures compatibility across different versions of the library.
 
-- MAJOR versions (x.0.0) might:
+[Semantic Versioning](https://semver.org) policy is used for library versioning, following the guidelines and limitations outlined below:
+
+- MAJOR versions (x.0.0) may:
   - target a new API version
   - include non-backward compatible change
-- MINOR versions (0.x.0) might:
+- MINOR versions (0.x.0) may:
   - add a new functionality, non-mandatory parameter or property
   - deprecate an old functionality
   - include non-backward compatible change to a functionality which is:
     - labelled as alpha or beta
     - completely broken and not usable
-- PATCH version (0.0.x) might:
+- PATCH version (0.0.x) will:
   - fix a bug
   - include backward compatible changes only
 
 ## More documentation
 
-More documentation and code examples can be found at <{{ documentationUrl }}>.
+Additional documentation and code examples can be found at <{{ documentationUrl }}>.
 
 ## Support
 

generators/common/templates/README_frontend_warning.mustache

@@ -0,0 +1,9 @@
+
+This library is for backend use only, as it requires secret Onfido API tokens and should not be used in the frontend due to security reasons.
+
+If you need to collect applicant data in the frontend of your application, we recommend that you use the Onfido SDKs:
+
+- [iOS](https://github.com/onfido/onfido-ios-sdk)
+- [Android](https://github.com/onfido/onfido-android-sdk)
+- [Web](https://github.com/onfido/onfido-sdk-ui)
+- [React Native](https://github.com/onfido/react-native-sdk)

generators/common/templates/README_webhook_verification.mustache

@@ -0,0 +1 @@
+Webhook events payload needs to be verified before it can be accessed. Verifying webhook payloads is crucial for security reasons, as it ensures that the payloads are indeed from Onfido and have not been tampered with. The library allows you to easily decode the payload and verify its signature before returning it as an object for user convenience:

generators/java/okhttp-gson/templates/README.mustache

@@ -2,13 +2,13 @@
 
 The official Java library for integrating with the Onfido API.
 
-Documentation can be found at <{{ documentationUrl }}>.
+Documentation is available at <{{ documentationUrl }}>.
 
-This library is only for use on the backend, as it uses Onfido API tokens which must be kept secret. If you do need to collect applicant data in the frontend of your application, we recommend that you use the Onfido SDKs: [iOS](https://github.com/onfido/onfido-ios-sdk), [Android](https://github.com/onfido/onfido-android-sdk), [Web](https://github.com/onfido/onfido-sdk-ui), and [React Native](https://github.com/onfido/react-native-sdk).
+{{ >README_frontend_warning }}
 
-This version uses Onfido API {{ apiVersion }}. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details of which client library versions use which versions of the API.
+This version uses Onfido API {{ apiVersion }}. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details. The guide explains which client library versions use which API versions.
 
-![Build Status](https://github.com/{{{ gitUserId }}}/{{{ gitRepoId }}}/actions/workflows/maven.yml/badge.svg)
+![Build Status](https://github.com/{{ gitUserId }}/{{ gitRepoId }}/actions/workflows/maven.yml/badge.svg)
 
 ## Installation & Usage
 
@@ -38,17 +38,17 @@ To deploy it to a remote Maven repository instead, configure the settings of the
 mvn clean deploy
 ```
 
-Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
+Refer to the [OSSRH Guide](https://central.sonatype.org/publish/publish-guide) for more information.
 
 #### Maven users
 
 Add this dependency to your project's POM:
 
 ```xml
 <dependency>
-  <groupId>{{{groupId}}}</groupId>
-  <artifactId>{{{artifactId}}}</artifactId>
-  <version>{{{artifactVersion}}}</version>
+  <groupId>{{ groupId }}</groupId>
+  <artifactId>{{ artifactId }}</artifactId>
+  <version>{{ artifactVersion }}</version>
   <scope>compile</scope>
 </dependency>
 ```
@@ -59,12 +59,12 @@ Add this dependency to your project's build file:
 
 ```groovy
   repositories {
-    mavenCentral()     // Needed if the '{{{artifactId}}}' jar has been published to maven central.
-    mavenLocal()       // Needed if the '{{{artifactId}}}' jar has been published to the local maven repo.
+    mavenCentral()     // Needed if the '{{ artifactId }}' jar has been published to maven central.
+    mavenLocal()       // Needed if the '{{ artifactId }}' jar has been published to the local maven repo.
   }
 
   dependencies {
-     implementation "{{{groupId}}}:{{{artifactId}}}:{{{artifactVersion}}}"
+     implementation "{{ groupId }}:{{ artifactId }}:{{ artifactVersion }}"
   }
 ```
 
@@ -78,10 +78,10 @@ mvn clean package
 
 Then manually install the following JARs:
 
-- `target/{{{artifactId}}}-{{{artifactVersion}}}.jar`
+- `target/{{ artifactId }}-{{ artifactVersion }}.jar`
 - `target/lib/*.jar`
 
-The latest version can be found at: https://search.maven.org/artifact/{{ groupId }}/{{ artifactVersion }}
+The latest version can be found at <https://search.maven.org/artifact/{{ groupId }}/{{ artifactId }}/{{ artifactVersion }}/jar>.
 
 ## Getting Started
 
@@ -106,7 +106,7 @@ DefaultApi onfido = new DefaultApi(Configuration.getDefaultApiClient()
                       .setReadTimeout(60_000));
 ```
 
-NB: by default, timeout values are set to 30 seconds.
+NB: By default, the connection and read timeout values are set to 30 seconds. You can adjust these values as shown in the configuration section.
 
 ### Making a call to the API
 
@@ -116,7 +116,7 @@ Most of the request bodies can be created using a builder pattern, this would lo
 new ApplicantBuilder().firstName("First").lastName("Last");
 ```
 
-The above will return an `Applicant.Request` object that can be provided to the `create()` method as the request body, so a full call to to the API will look something like:
+The above will return an `ApplicantBuilder` object that can be provided to the `createApplicant()` method as the request body, a full call to the API will look something like:
 
 ```java
 try {
@@ -141,7 +141,7 @@ try {
 
 ### Webhook event verification
 
-Webhook events payload needs to be verified before it can be accessed. Library allows to easily decode the payload and verify its signature before returning it as an object for user convenience:
+{{ >README_webhook_verification }}
 
 ```java
 try {
@@ -161,10 +161,10 @@ try {
 
 ### Don't share DefaultApi among different threads
 
-It's recommended to create an instance of `DefaultApi` per thread in a multithreaded environment to avoid any potential issues.
+It's recommended to create an instance of `DefaultApi` per thread in a multithreaded environment to avoid potential issues.
 
 #### Do not use additional properties
 
-Retain from using `getAdditionalProperty()` or `getAdditionalProperties()` methods to access not defined properties to avoid breaking changes when these fields will appear.
+Except for retrieving Task object's outputs, avoid using `getAdditionalProperty()` or `getAdditionalProperties()` methods to access undefined properties to prevent breaking changes when these fields appear.
 
-{{>README_footer}}
+{{ >README_footer }}

generators/java/okhttp-gson/templates/README_frontend_warning.mustache

@@ -0,0 +1 @@
+../../../common/templates/README_frontend_warning.mustache

generators/java/okhttp-gson/templates/README_webhook_verification.mustache

@@ -0,0 +1 @@
+../../../common/templates/README_webhook_verification.mustache