Let there be docs! A documentation-first approach to Rails API development

At FriendlyRB, in Bucharest, Romania


Share on

Are you tired of custom DSLs, lack of OpenAPI features and endless complaints about your docs? Say no way to RSwag and Grape. Be radical—start writing pure OpenAPI YAMLs. This isn’t your dad’s API design–it’s the future! Get ideal docs and robust testing with this documentation-first approach.

Rails is certainly known for its full-stack development powers—but it’s also great for API development. Still, even though it makes API work easy to start, moving from prototyping to production Rails can see a number of potential missteps, like a lack of good documentation. This can lead to miscommunication within the team, and oh-so-delicate test suites.

Developers often try to fix these issues with complex tools like RSwag and Grape, but, unfortunately, they just end up with more tricky stuff to deal with. Plus, these tools usually treat documentation as an afterthought instead of a key part of app development.

However, in real life, docs are the primary source of truth for API consumers. And here, we come to my talk: I’ll introduce a documentation-first methodology that uses the power of Test-Driven Development (TDD) to create robust APIs. We’ll see how to effectively adopt this approach in Rails, starting with writing comprehensive API documentation that will be a reliable reference for consumers—we’ll make sure docs are an integral part of app development, rather than just another artifact.

I’ll explore real examples, discuss possible pitfalls, and give actionable solutions that show how to easily and efficiently transition from prototype to production. We’ll banish exceedingly complex old school API design and replace them with pristine OpenAPI YAMLs. With this approach to Rails development, you’ll enhance team communication, build more robust test suites, and ultimately create better products.


In the same orbit

Explore more events

Let's solve your hard problems

Martians at a glance
years in business

We're experts at helping developer products grow, with a proven track record in UI design, product iterations, cost-effective scaling, and much more. We'll lay out a strategy before our engineers and designers leap into action.

If you prefer email, write to us at surrender@evilmartians.com