Share:
.svg)
.svg)
Exciting news! Customizing your SDKs just got easier with improved CodeGen settings documentation.
We've heard your feedback on the documentation for our CodeGen settings. This important feature in APIMatic includes 80+ settings that allow you to customize both the code libraries and documentation generated for your APIs. You told us our existing CodeGen setting docs lacked the detail to truly understand and utilize these powerful settings. So we rolled up our sleeves and gave it a major makeover.
The result? A comprehensive and exciting new resource built with you in mind.
CodeGen settings before the makeover
Previously, our CodeGen settings documentation was limited to a single HTML page with basic information about some 80 settings. This information was limited to the setting’s name, its type, and a one or two sentences on its purpose.
Talking with customers, we realized better organization and more details around CodeGen settings were needed to empower users to customize their SDKs.
CodeGen settings docs glow-up
Our team put a lot of thought and effort into this project to improve the overall developer experience, and we're thrilled to share the results with you.
Here are the highlights:
Similar settings grouped together
One of the first things we did was logically group the settings into separate sections, making it easier to navigate and find what you need.
I’m listing the main groups that contain related settings.
Endpoint settings
This group contains all settings that have a major effect on the endpoints.
(i.e. UseHTTPMethodPrefix, PreserveParameterOrder, UseEndpointMethodName)
Model settings
This group contains settings that manage a model-specific behavior in the generated SDKs.
(i.e. EnableAdditionalModelProperties, GenerateModels, EnableImmutableModels)
Enumeration settings
This group contains settings that provide control over generated enums in SDKs.
(i.e. GenerateEnums & UseEnumPrefix)
Package configuration settings
This group explains settings that help configure the SDK package. Settings like JavaGroupId, PHPComposerPackageName are defined in this group.
These are code generation settings that let you manage HTTP configurations in the SDKs.This group contains setting like EnableHttpCache, AppendContentHeaders, AllowSkippingSSLCertVerification, etc.
SDK interface customization settings
This group contains the most CodeGen settings. You have settings like ProjectName, CSharpNamespace, ControllerNamespace that let you take control of the overall look and feel of the SDKs.
This group contains settings that allow control over retries and exponential backoff of API calls from the generated code. These settings include RetryOnTimeout, StatusCodesToRetry, RetryInterval etc.
Then you have groups for Serialization settings, User agent, Code branding, SDK docs configuration, Exception settings, and unrelated settings placed inside a Miscellaneous group. I won’t go into much detail here and leave you to check all these settings yourself.
CodeGen settings usage details added
We created a usage section for each CodeGen setting. Helping users understand the specifics of using a setting prepares them to actually implement it and customize their SDKs.
The additional usage section contains three pieces of information: type of the setting, its default value, and a code snippet explaining how to tweak their OpenAPI definition file to configure the setting.
Which CodeGen setting speaks your language?
We’ve also included a language table to communicate which language SDKs will be modified by the setting.
Story of transformation in your SDK
And, for settings that have a visual impact on the SDK, we've introduced a section that allows you to visualize the effect of a setting on the generated SDK. This table shows before and after configuration details, so you can easily pinpoint the changes in your SDK.
Unlock the changes in API docs
If there are any code generation settings that visually affect API docs, then we have covered the change in this release as well. Now, you can have a better understanding of what configuring a setting will change - inside the SDK as well as on the portal.
Overall, we're thrilled with the results of this makeover. We believe it substantially improves the developer experience of our customers by offering a comprehensive guide to our extensive CodeGen settings.
Your feedback is important to us
We're always listening to our customers and striving to provide the best possible experience. We hope our improved documentation helps you get the most out of our product, and we welcome your continued feedback.
Get ready for a better CodeGen experience with APIMatic!
