OpenAPI code generation
The FormFlow API has been built to integrate with the OpenAPI specification. This specification allows for a standard way of defining APIs. This paves the way for an entire community of tools and open source projects to interact with APIs to enhance the developer experience.
For details please refer to the OpenAPI Initiative.
Client code generation
For building out your own customization using the FormFlow API you can leverage the OpenAPI Code generation tool to produce an API client in many different languages.
To get started, follow the instructions at https://github.com/OpenAPITools/openapi-generator.
Once installed, you can generate a client from the command line. It requires access to the OpenAPI specification URL for your ThoughtFarmer installation. These are all available from /formsapi/swagger/v1/swagger.json. Add that to your root URL (e.g. https://myIntranet.com/formsapi/swagger/v1/swagger.json).
From the command line or PowerShell you can then run commands to generate the client API of your choice. Refer to the OpenAPI Generator documentation for details.
An example of generating a TypeScript client using jQuery to make the ajax calls is:
openapi-generator-cli generate -i "https:/myIntranet.com/formsapi/swagger/v1/swagger.json"
-g typescript-jquery -o ./generated/typescript/src
This outputs the generated client into a subfolder /generated/typescript/src.
Another example to generate a C# API Client using more advanced configuration options is:
openapi-generator-cli generate -i "$siteRoot/formsapi/swagger/v1/swagger.json"
--generator-name csharp-netcore -o ./generated/csharp
--package-name "ORC.TF.Forms.PublicAPI.Client"
--global-property apiTests=false,modelTests=false --skip-overwrite
OpenAPI versions
The latest OpenAPI version is v3. The specification at /formsapi/swagger/v1/swagger.json will be in OpenAPI v3 format by default. Some client generators may not be compatible with v3 yet. If you need the specification to be in v2 it is possible to change this.
On-Premise clients
Go to the ThoughtFarmer Admin panel: Advanced section > Configuration settings page. Look for the setting forms.publicapi.openapi.version. Change this to V2.
In IIS on the server you must recycle the application pool associated with the FormFlow application. This is different then the main site application pool. This is required to pick up the configuration change and update the specification version at /formsapi/swagger/v1/swagger.json. If you go to the main auto-generated documentation page at /formsapi/apidocs/index.html you should see an OAS2 tag beside the API's title.
Cloud clients
Please submit a Helpdesk request for our Support team to assist you in making this change.
Comments
0 comments
Please sign in to leave a comment.