Where to store your OpenAPI definitions

In a series of posts, organizations can learn how to effectively utilize OpenAPI definitions, source control repositories, and Redocly products to enhance API documentation and development. Redocly's developer portal facilitates collaboration between developers and technical writers by providing all necessary API information, which includes guides and examples. The text outlines three approaches for managing OpenAPI definitions: co-locating them with code in a single repository, maintaining them in a separate dedicated repository, and synchronizing them between code and dedicated repositories. Each approach has its advantages and challenges; for instance, the first approach promotes synchronization with the code but may raise security concerns, while the second approach eases access for non-developers but requires manual synchronization. The third approach ensures synchronization but involves complex workflows. Redocly suggests starting with the first approach for its simplicity and ease of implementation, while the subsequent approaches cater to specific organizational needs and team dynamics. The discussion is set to continue in future posts, with a focus on implementing a two-way sync between Git repositories.