As explained here, an API specification transformation internally involves both import and export stages behind-the-scenes. Both these stages can be configured individually for which two major ways are described below:
Using APIMatic Metadata Configuration Options
You can transform your API definition/specification along with the APIMatic's Metadata file that will allow you to do the following:
- Configure the import stage of the transformation process.
- Configure the export/conversion stage of the transformation process.
- Merge API specifications together before transforming them.
- Filter the API specification document before transformation.
- Override parts of the API specification document before transformation.
You can control and customize how your file is imported during the transformation process e.g. you can configure the import process to use the schema keys instead of schema titles during OpenAPI import.
The import level configuration is performed by using import settings that are provided inside the APIMatic Metadata file Import Settings Object.
Import Settings Object
The available properties in this object and their respective types are listed here.
You can control and customize how your input file is exported during the transformation process e.g. you can enable/disable export of vendor extensions when exporting to OpenAPI.
The export level configuration is performed by using export settings that are provided inside the APIMatic Metadata file Export Settings Object.
Export Settings Object
The available properties and their respective types are listed here.
Merge and Transform
If you have multiple API definitions that you wish to merge together and produce a single transformed file in a particular format, you can enable merging in the ZIP folder you upload.
Merging multiple definitions is different from handling multiple files of a single API definition, which is handled by the Transformer automatically.
To enable and further configure merging, you need to add a Merge Configuration Object in the Metadata file.
API Merging Settings
The available merging configurations are listed here. These configurations further contain a Merge Settings Object to configure how any two APIs are merged together.
"MergeOrderOfDirectories": ["SpecDirectory1", "SpecDirectory2"],
"MergedApiName": "Merged API",
Merge Settings Object
The Merge Settings Object allows configuration of the merge process. The settings available are listed here.
When merging multiple API definitions for purpose of transforming the output, we recommend that you turn off strict validation meant specifically for Code Generation use-cases. This can be done by enabling the merge setting
SkipCodeGenValidation as shown in the example in the previous section.
Filter Before You Transform
If you wish to remove certain endpoints (for privacy reasons or any other) and their related data from the API specification document without actually affecting the original document, you can enable filtering using filtering options in the Metadata file. For more details, please see relevant section here.
Override Parts of API Definition Before You Transform
If you are looking to override certain parts of the API definition before transforming it, you can take a look at some of the overrides available in the Metadata file here.
Using Format-Specific Vendor Extensions
We also support format-specific vendor extensions (e.g. for OpenAPI/Swagger, RAML and API Blueprint) so you can fine-tune the transformation output from within your API specification file. For details, please refer to our detailed documentation on Extensions specific to your API definition file.