Engineering, APIs

API Documentation

August 5, 2020

For years BriteCore used the tried and tested Sphinx tool to create technical documentation for our APIs at api.britecore.com. Sphinx is a well-regarded tool that is in common use, but it does not automatically produce OpenAPI documents.

As is so common with manual processes, they can be difficult to maintain over time as organizations change and teams are constantly juggling priorities.

Recently we made several improvements to api.britecore.com to address this documentation challenge with automation. Each of our services run through a pipeline for building, testing, and packaging before we make it available for deployment. As part of that pipeline, services may provide OpenAPI specifications. The OpenAPI specification provides technical documentation for consumers of the API. Those specifications are now automatically created and deployed to api.britecore.com. This eliminates the former dependency on manual updates and ensures that our customers always have the latest technical documentation.

This change also frees up BriteCore resources to expand the level of support we can provide with additional instructions or making use of new capabilities. We look forward to providing you with new guides and examples to help you build on the BriteCore platform.

Related Articles

Effective Engineering Communication
BriteCore's global engineering force comes from all different backgrounds and cultures. As we've grown, we've learned that effective engineering communication is key to delivering real value.
Stop Bike-Shedding, Start Automating
Avoid trivial bike-shedding in GitHub Pull Request reviews with the help of automation.
Useful Unit Tests: Why Do They Matter?
Unit tests are the foundation of every test suite, and following the property of readability can ensure those tests are useful and saving your team time and money.