// the find
Apipie/apipie-rails
Ruby on Rails API documentation tool
Apipie-rails is a DSL for documenting Rails APIs inline with your controller code, with optional parameter validation and Swagger/OpenAPI 2.0 export. It targets Rails shops that want their docs to live next to the code rather than in a separate YAML file. The built-in browser UI at /apipie is a reasonable way to share docs with frontend teams or API consumers.
The param_group / def_param_group system for sharing parameter definitions across create/update actions is genuinely useful and avoids the copy-paste drift that kills most hand-maintained API docs. Action-aware params (auto-adjusting required/allow_nil based on whether you're in a create or update context) is a clever solution to a real CRUD annoyance. The test integration — recording real request/response pairs from your RSpec suite and generating examples automatically — means docs stay honest as the API evolves. The `describe_own_properties` hook for self-describing model classes is a nice escape hatch when your JSON generation is encapsulated in serializer objects.
The Swagger export is stuck on OpenAPI 2.0, which predates most tooling people actually use today — no OpenAPI 3.x means no support for oneOf/anyOf, no request body objects, and awkward workarounds for anything that doesn't fit 2.0's data model. The DSL is Rails-controller-centric, so if you're using anything other than classic Rails controllers (Grape, Hanami, plain Rack middleware) you're on your own. The bundled frontend (Bootstrap 2-era HTML, jQuery, Prettify) looks like it was frozen in 2013 and hasn't been touched; it's functional but embarrassing to hand to a client. Validation behavior (the `validate` config option with `:implicitly`/`:explicitly`/`false` states) wraps controller action methods at load time in a way that can interact badly with other around-filters and is hard to debug when things go wrong.