August 2018 Summaries

Kanad has joined the Minnesota branch of the ReadMe team and is enjoying exploring Minneapolis on his newly purchased bike, although he is not particularly fond of the pedaling aspect. During his rides, he often listens to Janelle Monáe, who has been his favorite artist on Spotify for five consecutive years. Interestingly, Kanad recently discovered that the hospital where he was born was closed down due to malpractice a few years after his birth.

ReadMe has introduced an enhanced publishing flow that defaults new documentation, blog posts, and custom pages to an unlisted status, allowing creators to refine content without the risk of premature public exposure. Once published, any subsequent edits affect the live version, but users can choose to unlist the document again, making it accessible only through a direct link. This update, which has significantly improved internal workflows, is now being made available to all users.

ReadMe's API explorer faced challenges in supporting complex JSON Schema structures due to its origins when Swagger/OAS usage was limited, requiring API creation within their Dashboard. Despite this, it remains a popular method for documenting endpoints, allowing direct uploads of Swagger and OAS files to document API parameters, including various nested and primitive structures. Initially, the explorer struggled with deep nesting, arrays of primitives, and top-level values, leading to issues in rendering and input forms. However, recent updates have improved support for deeply nested objects, better handling of primitive arrays with appropriate input elements, and support for top-level arrays and primitives. The API Explorer is now open source, inviting users to report unsupported types and explore its capabilities further.

The announcement highlights the completion of a highly requested feature: the new API Explorer, which now supports the OpenAPI 3.0 (OAS 3.0) Specification alongside the existing Swagger 2.0 files. Initially, ReadMe only accepted Swagger 2.0 files, but with the release of OAS 3.0, the team utilized the swagger2openapi package to convert specifications and the swagger-parser package to parse, validate, and resolve these files, simplifying the integration process. The new API Explorer is automatically enabled for projects created after July 6, 2018, while older projects can soon opt-in through settings. Users are encouraged to test the new API Explorer with their current Reference documentation using a specific query parameter and report any issues. New API endpoints have been established for handling OAS 3 files, and while the rdme CLI program lacks a dedicated OAS command, it can process OAS files using the existing swagger command. Special thanks are extended to contributors for their support in developing these features.