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

At FriendlyRB, in Bucharest, Romania
Cover for Let there be docs! A documentation-first approach to Rails API development


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.

Attend the event

Explore more events

Contact us

We’d love to hear from you! We’re not really all that evil, and we love discussing potential projects, intriguing ideas, and new opportunities. Complete the form below or drop us a line at surrender@evilmartians.com. Alternatively, schedule a Calendly appointment with us right now!

Martians at a glance
years in business

A product development consultancy that works with startups and established businesses, while also creating open source-based products and services