May 2022 Summaries

Redocly users have expressed a need for a more accessible "data dictionary" for API objects, as the current method of accessing schemas in OpenAPI is seen as cumbersome. The existing implementation is outdated and not user-friendly when displaying multiple schemas or organizing them effectively. To address this, two new approaches have been introduced in the Developer portal 1.1.0-beta.95. The first approach involves grouping all schemas together in a sidebar using the schemaDefinitionsTagName configuration in the Redocly configuration file, while the second approach allows schemas to be tagged with operations using the x-tags specification extension. These features allow for a more organized and accessible display of schemas, ensuring that they can be displayed either collectively or alongside relevant operations as needed.

The blog post critically examines the proposed overlays for the OpenAPI Specification, highlighting the complexity and limitations of the approach. Although overlays aim to generate a new OpenAPI definition by combining an original definition with an overlay document to address use cases such as adding, removing, or merging information, the author argues that the proposal is flawed. The post outlines issues such as the complexity of learning both the overlays and JMESPath specifications, incorrect example implementations, and the lack of effective tools to process overlays. Instead, existing solutions like decorators for removing internal APIs and overriding descriptions are recommended as practical alternatives. The author suggests that the OpenAPI steering committee reconsider the overlays proposal, advocating for simpler, more effective solutions that meet current user needs without introducing unnecessary complexity.

The text discusses how to remove a logo from the OpenAPI documentation using Redocly, focusing on two simple methods: removing the x-logo reference directly from the OpenAPI file or using the hideLogo feature toggle in the Redocly configuration. The x-logo is a specification extension added to the info object, and when present, it displays a logo in the top left corner of the documentation. By removing the x-logo object from the OpenAPI file or activating the hideLogo feature toggle, users can prevent the logo from being displayed without needing to modify the HTML directly. These methods offer flexibility depending on whether users can edit the OpenAPI file or prefer using configuration settings.

In exploring how to manage shared schemas for multiple API endpoints, a solution involving the use of the allOf keyword in OpenAPI is suggested to address the issue of differing field requirements for "create" and "update" operations. By maintaining a shared Address schema, developers can create an additional schema that references the original and uses allOf to specify required fields for particular endpoints without overriding existing values. This approach allows for flexibility, enabling fields to be optional for updates but mandatory for creations. The process is demonstrated through a minimalist OpenAPI definition and highlighted in example API documentation, showing the correct application of required fields in different contexts.

In April 2022, Redocly focused on "spring cleaning," addressing technical debt and enhancing product features. Notably, Australia Post reduced its developer bounce rate by using Redocly's Developer portal. Significant updates included infrastructure improvements for Workflows, a new sidebar customization option in Reference docs, improved search usability on API reference pages, and enhancements to OpenAPI CLI commands, particularly the push and lint commands. Redoc introduced theming options for better sidebar navigation. Although Redocly did not make the final selection for Google's Season of Docs 2022, they remain optimistic and are actively recruiting a Technical Writer and Developer Advocate to expand their documentation and engagement efforts.