Shipping API Docs Under Pressure
I’ve been lucky enough to work on many different types of projects at thoughtbot, and it always amazes me how important it is to adapt not only to the style of the project, but to the style of the business behind it. I currently find myself consulting on a fast-paced startup application for trading crypto. This is a very different environment to one of my previous clients, which was a mature enterprise fintech business.
Yet both enterprise and startup projects have one thing in common. The QA team requires API documentation so they can test the APIs before we deploy to production.
In the enterprise world, there’s usually time to consider the best way to maintain API documentation. I’ve seen great uses of the OpenAPI Specification, and even teams running automated tests against those specs to ensure everything stays up to date.
But in my current environment, there’s no such luxury. We don’t have the time to architect and curate the perfect solution. We need something that’s good enough and reliable within the constraints we’re working under. We need to get something to the QA team that allows them to test the API fast.
Enter thoughtbot’s latest Claude Skill to generate Postman collections!
This Claude Skill was born out of a very real need, keeping API documentation up to date without adding a big maintenance burden. Instead of hand-maintained docs that quickly drift from reality, this tool generates a Postman collection directly from your Rails controllers.
What is a Claude Skill?
If you haven’t come across Claude Skills yet, they’re essentially small, focused automations that use Claude to perform a specific task. You can read more about claude skills here.
In this case, the skill gives Claude clear instructions and context about how to interpret a Rails app, what to look for in controllers, and how to turn that into a Postman collection. You run it locally, Claude does the heavy lifting, and you get a concrete artefact checked into your repo. A Postman collection committed to the root of the repository that QA and fellow developers can use immediately to explore, test, and understand the current API surface.
How it works
The skill scans your Rails controllers and extracts useful information such as:
- Routes and HTTP methods
- Controller actions
- Required and optional parameters
- Headers and authentication hints
From this, it generates a ready-to-use Postman collection in JSON format.
You can even run it as part of CI or a release process, so the collection stays fresh without relying on human discipline (which, let’s be honest, is always the first thing to go under pressure).
Limitations
I have found that telling the LLM to look through the actual code helps the collection to be accurate. Of course it can make mistakes but that is why it is important to iterate on a skill to assist the LLM to be as accurate as possible. I would add that if you are spending too much time correcting the skill you might have reached a point where the cost of maintaining the skill outweighs the benefit of the time it saves.
For example, in the first iteration of this skill it was checking through all the API controllers in the codebase each time I asked it to generate the postman collection. Whilst this was thorough, it was taking a long time and I only really needed it to make changes based on the latest editions. I therefore added an initial step where it checks for any API related changes first that differ between the current working branch and main.
The skill also relies on RSpec test files in spec/requests to help build the collection. You can run it without specs but this may reduce the accuracy of the skill.
Final thoughts
This skill has genuinely helped us focus our time and energy on higher-value areas of the project, without leaving QA scrambling for documentation or relying on disparate knowledge.
It’s fully open source, actively maintained, and very much shaped by real-world constraints. If you’re in a similar situation, especially in a fast-moving team where “perfect” is the enemy of “useful”, it’s well worth a look.
Feedback, issues, and contributions are very welcome 🙂
Find the skill on GitHub
