March 2026 Summaries

OpenAPI 3.2, released in September 2025, introduces several enhancements such as support for streaming APIs, hierarchical tags, new HTTP methods, and updated security flows, all while maintaining backward compatibility with previous versions. The release simplifies navigation in larger APIs by allowing tags to be organized hierarchically, a feature similar to Redocly's x-tagGroups extension. It also introduces support for streaming media types like text/event-stream and application/jsonl with a new itemSchema field for describing each stream item's shape. The QUERY method is now supported, suitable for complex search operations, and additional HTTP methods can be specified with the new additionalOperations field. Security updates include support for OAuth 2.0 Device Authorization Flow and the ability to mark security schemes as deprecated. New example fields, dataValue and serializedValue, help clarify the structured data and serialized representations, especially for encoded parameters. Other noteworthy features include a new queryString parameter location, XML nodeType mapping, and defaultMapping on discriminators. Redocly fully supports OpenAPI 3.2, allowing users to seamlessly upgrade and utilize these new features without disrupting existing implementations.

SEO for documentation is crucial for ensuring users can effectively find technical content, focusing on technical quality assurance rather than traditional marketing tactics. Key practices include optimizing information architecture, crawlability, and precise version control without resorting to keyword stuffing or other aggressive SEO techniques. This involves using standard HTML for navigation to ensure crawlability, avoiding client-side JavaScript that hinders indexing, and employing canonical tags to manage duplicate content from different documentation versions. Effective use of sitemaps and unique, descriptive page titles can enhance discoverability, while addressing broken links and improving site performance through strategies like static site generation and lazy-loading can prevent user frustration and enhance search engine rankings. Additionally, automating SEO maintenance at scale by using platforms that integrate these best practices can prevent errors and ensure documentation remains accessible and authoritative.