February 2025 Product Highlights: OpenAPI Linting on GitHub and enhanced Portal customization

This month’s release introduces APIMatic OpenAPI Linter for GitHub, making it easier to enforce high-quality API definitions directly within your CI/CD workflow. We’ve also enhanced our Docs as Code workflow with asynchronous API portal generation for large API ecosystems. Additionally, new customization options, improved theming, and several bug fixes ensure a smoother experience across SDKs and API documentation.

Ensure High-Quality API Definitions with APIMatic’s GitHub App

We’ve launched APIMatic OpenAPI Linter, a GitHub App designed to help you maintain high-quality OpenAPI definitions specifically optimized for Code Generation and API Documentation. With this app, you can enforce API Definition quality at scale across your organization and introduce API Consumer Experience considerations into your API development workflow. 

Here’s what’s included:

• Automated validation on PRs – Run checks automatically when a pull request is created or updated, using 1,200+ CodeGen-specific rules.
• GitHub Checks integration – View validation results directly in PRs for quick issue resolution.
• Validate multiple API Definitions – Validate multiple OpenAPI definitions in the same repository, either separately or after merging.
• Comprehensive issue reports – Generate shareable reports with detailed insights and suggested improvements.

APIMatic’s API Definition Linting and Validation toolkit is the first CodeGen-specific solution of its kind, helping teams proactively improve API definitions for SDK generation and documentation. This latest addition expands APIMatic’s suite of API quality tools, alongside:

• Score my API – Instant OpenAPI quality assessment
• APIMatic for VS Code – Validate, Lint and auto-fix API Definitions in your IDE

🔗 Learn more in our documentation or install the app from the GitHub Marketplace.

Enhanced Theming with Dark Mode

We've introduced Dark Mode support to our Developer Portal, allowing users to switch between Light and Dark themes seamlessly. This enhances the viewing experience for developers working in different lighting environments while maintaining your brand consistency.

With improved theme customisation capabilities, you now have greater flexibility to align the portal's appearance with your brand identity. Developers can choose their preferred viewing mode, reducing eye strain during long coding sessions.

🔗 Learn more about how to enable Dark Mode on your Developer Portal.

Asynchronous Docs as Code workflow for large API Portals

Generating API Portals for large and complex API ecosystems just got more efficient. APIMatic’s Docs as Code offering now supports an Asynchronous workflow, making it easier to handle large API Portals where generation time exceeds a few minutes.

With this update, you can trigger portal generation and receive a callback notification when your Portal is ready for deployment. 

🔗 Learn more about the Asynchronous Docs as Code workflow.

📖 Blog: How to Design a Quick Start Guide for Your API

A quick start guide covers the minimal steps required for developers to make their first API call successfully. It typically provides steps such as how to create an account, where to locate API keys or credentials, how to authenticate, example code to make a basic API call, a way to display the response, and troubleshooting tips. The goal is to deliver a quick win to developers and provide a foundation to integrate with your API. Read More …

🛠 Improvements

• Easier Test Configuration with Environment Variables: The Python SDK now supports configuring test settings via environment variables, eliminating the need for hardcoded values in your test setup.

• HTTP Verbs Display for All Languages: A new portal setting enableHttpVerbsForAllLangs, allows you to display HTTP method tags (GET, POST, PUT) in the left navigation bar for all programming languages, not just HTTP. This improves navigation consistency and is available exclusively for Docs as Code users. Enhanced Visibility for Deprecated Endpoints: We've improved how deprecated endpoints are displayed throughout the portal, making them instantly recognizable to developers. These enhancements include clearer labeling, improved guidance on recommended alternatives, and intuitive UI changes to help developers avoid accidental usage of outdated APIs.
• Enforce Required Fields with Custom Validation Rules: You can now define custom validation rules to enforce required constraints on objects that are not explicitly defined as required in the OpenAPI Specification, such as vendor extensions. This rule ensures that target objects include all necessary properties and that each property holds a valid value.
• Customize Parameter Names with x-unique-name: We’ve added a new OpenAPI Extension x-unique-name  to override the name for any object in an API Definition. You can now disambiguate similar parameter names or simply provide more Developer friendly names without modifying your API implementation. 

🐞 Bug Fixes

• [Java] Improved network resilience by enabling automatic retries in the OkHttp client for transient failures (e.g., timeouts, connection resets).
• [PHP] Fetch token calls no longer throw a type error on using invalid credentials when the ReturnCompleteHttpResponse CodeGen setting is enabled.
• [Python] Optional properties in the string representation of models are now correctly formatted for accurate output.
• [Go] OAuth 2.0 refresh token flow no longer fails due to pointer conversion issues.
• [Python, Ruby] Auth URL generation for OAuth 2.0 Authorization Code Grant now correctly applies server configuration settings.
• [Ruby] Authentication parameters in the OAuth 2.0 fetch token flow are now handled correctly, preventing method invocation errors.
• [Python] SDK-generated docstrings now comply with maximum line length requirements for better readability.
• [API Specs] Empty fields in XML schema examples are no longer ignored in the documentation.
• [Validator] Inline schemas that define a ‘title’ property no longer trigger an inline schema violation error.

⚠️ Deprecations & Breaking Changes

• Deprecated themeOverrides object for Docs as-code customers: The themeOverrides object in the build file has been deprecated and will no longer be supported or maintained.

Next steps:

• • Migrate to the new theme object in your build files
  • Update any automation or CI/CD pipelines that reference the old object

Impact:

This change requires updates to your build configuration files. Any existing portals using themeOverrides will continue to function but may not receive visual updates in future releases.

🔗 Check out the documentation for:

• • Legacy themeOverrides object
  • New theme object

📢 Share your feedback

Your feedback makes our product better.

• 🐞 Found a bug? Report it at support@apimatic.io and earn eternal developer karma.
• 💡 Got a brilliant idea? Jump on a call and share it before our product team claims they thought of it first - Schedule 15 mins.
• 🎉 Love something we built? Tell us so we can argue less about what to build next.

Follow us on LinkedIn or join our public Slack Workspace to stay updated with the latest news from APIMatic!