We're releasing a new version of our Developer Experience Portal which improves docs generation for all SDKs. This is a breaking change and requires manual migration. Check out all the changes below.
Change in Naming Scheme Affecting Titles
We're changing the default naming scheme for sections in the docs. Instead of using SDK-specific endpoint, controller and custom-type names for titles, we'll now be using the original names from the API specification making all titles SDK-agnostic.
All names will be title-cased and sanitized for use in the documentation. Original names might have been written as camel-cased or snake-cased but APIMatic will automatically convert them to title-case.
How Title-Casing Works
Title-casing names means that:
- Camel-cased and pascal-cased names are converted to space-separated words.
- All symbols will be removed from names, except for hyphens.
- Multiple consecutive spaces are reduced to just one space.
- First letter of each word is capitalized.
Here are some examples:
| Original Name | Title-Cased Name |
|---|---|
| Some string | Some String |
| SomeString1_2_3 | Some String 1 2 3 |
| SomeEXEString | Some EXE String |
| Some-string | Some-String |
| GetStringByName | Get String by Name |
| string-by-name | String-by-Name |
Do-Not-Split Words Support
Do-Not-Split words lets you specify a list of words that should not be split during naming conversion. This helps converting names that have unconventional capitalization such as "VMware" which would otherwise be title-cased as "V Mware".
Adding such words to the do-not-split-words list prevents this from happening in titles generated in the docs as well as identifiers created in the SDKs.
Simplified URL Scheme
Our new URL scheme is similar to the scheme used on GitHub for generating hash-ids for headings. The URLs are derived from titles and therefore, will respect Do-Not-Split Words list as well. This scheme also works better with abbreviations in titles.
Besides this, we've also moved some SDKs to shorter URLs and added redirections for their old paths:
| SDK Platform | Old path | New Path |
|---|---|---|
| PHP | /php-composer-libary | /php |
| AngularJS | /angular-js | /angularjs |
| Java | /java-maven-libary | /java |
Custom Guide Titles Now Included By Default (Fix)
Titles for custom-guides were not previously added as heading to the top of the guide pages. This lead to inconsistency between guides and duplication of title in guide content.
We've rectified this and made sure titles will always appear on top of guide pages. However, this means that you'll have to remove the extra heading from the guide content if you've added one before migration.
HTTP Method Prefix Flag Always Respected (Fix)
Endpoint names are now consistently prefixed according to the HTTP verb across HTTP and SDK docs if the UseHttpMethodPrefix flag is on in CodeGen settings. If you don't want the endpoint names to be prefixed, please turn off this flag.
CodeGen Settings can be changed via our editor. They can also be added to your API specification file via our extensions for Swagger/OAS 2, API Blueprint and other formats.
Syntax Highlighting (Fix)
We've made several improvements to our syntax highlighter, improving its accuracy and fixing incorrect detection of language snippet for highlighting.
We've also added highlighting for the HTTP method signature in our HTTP docs.
Migrating to the New Release
This release is available to all existing and new customers. This section describes how to upgrade your portal version to this release.
Please test the URLs for all the API Endpoints and Models pages. These URLs might have changed due to the change in naming-scheme for titles. Also, custom guides' content must not repeat the title as a heading because the title is now included by default.
Portals Embedded in Websites
Customers who have embedded portals in their website should generate a new snippet for embedding.
Portals Hosted on APIMatic
Customers who have portals hosted on APIMatic will be contacted for migration.
White-Labelled Portals
Customers who have white-labelled portals will be contacted for migration.