Apipie-rails: API Docs Written in Ruby, Not in Comments

The problem Apipie-rails solves for Rails API authors

Most API documentation drifts because it lives somewhere other than the code. A comment block above an action, a YAML file, a separate spec suite: each one is a second copy of the truth, and the copy that ships is the controller. Apipie-rails takes the opposite position. The README states the project is a DSL and Rails engine for documenting RESTful APIs, and that instead of the traditional use of #comments it lets you describe the code through the code. The stated advantages are that you already know Ruby, that the docs can be reused for other purposes such as validation, that there is no string parsing to maintain, and that other sources such as routes can feed the documentation.

That framing tells you who it is for. If your endpoints are Rails controller actions and your team is comfortable reading Ruby macros, the documentation becomes part of the method definition rather than a parallel artifact. If your API is generated elsewhere, or your team writes specs first and treats controllers as an implementation detail, the same design becomes friction: you are adding declarations to files that other people own.

How the DSL and the Rails engine fit together

Apipie-rails is a Rails engine, so it mounts its own documentation interface inside your application. The README says the documentation is available from within your app, by default under the /apipie path, and that in development mode you can see changes as you go. The same content is exposed as data at /apipie.json for further processing, which is the hook other tooling uses.

Descriptions are attached at two levels. A controller declares itself with resource_description do ... end, and the README lists the keywords that block accepts: resource_id, name, short, desc, param, returns, api_base_url, api_versions, formats, error, app_info, meta and deprecated. Inheritance is supported, so common params for a group of controllers can live in a parent class instead of being repeated. Individual actions are annotated with api and param, and the param declarations are not decorative: the README lists validators for type, regexp, enum, proc, hash, nil, number, decimal, array and nested values, plus an API for adding a custom validator. That is the reuse the README means when it says the docs can serve validation as well as documentation.

The markup is described as agnostic, and there is a separate configuration section for versioning, localization, static files and Swagger generation. The important architectural point is that Apipie-rails parses Ruby structures, not comment strings, so a typo in a param name is something the Ruby parser and the validator layers can see, not something that silently renders wrong.

Installing the gem and documenting a first action

The README gives a three-command installation. The gem line goes into the Gemfile, Bundler resolves it, and a generator writes the initial configuration:

echo "gem 'apipie-rails'" >> Gemfile
bundle install
rails g apipie:install

After that, the README shows the minimal annotation for an action: an api line naming the HTTP verb and the path, then a param line describing an argument. The example in the README is a show action taking a numeric id:

api :GET, '/users/:id'
param :id, :number, desc: 'id of the requested user'
def show
  # ...
end

Start the application and the README says the result is at http://localhost:3000/apipie. For programmatic use, the same documentation is available at http://localhost:3000/apipie.json. What you should see is a browsable page listing resources and their methods, with the parameter table derived from the param lines rather than from anything you wrote twice. The README points to a separate demo repository, apipie-demo, for a longer walkthrough that covers generating documentation from tests and recording examples.

Where Apipie-rails gets in your way

The DSL lives in the controller, and that is the trade-off, not a side effect. Every action you document grows a few lines of declarations above the method body. On a controller with ten actions, the documentation can be longer than the code it describes, and a reader who only wants to know what the method does now scrolls past param blocks first. The README's own framing, describe the code through the code, is honest about this: the docs are not free, they are paid for in controller readability.

The second constraint is output format. The configuration reference covers static Swagger (OpenAPI 2.0) files and dynamic Swagger generation, and the Swagger section carries its own list of known limitations of the current implementation. If your consumers already expect OpenAPI 3 documents, the README does not document an OpenAPI 3 path, so you would be converting the 2.0 output downstream. The README also notes that Swagger generation can produce warnings, which is a signal that some DSL constructs do not map cleanly onto the Swagger model.

There is also a documentation gap worth naming: the README's License section says Apipie-rails is released under the MIT License, while the repository root contains both an MIT-LICENSE file and an APACHE-LICENSE-2.0 file alongside a NOTICE file. The README does not explain which applies to which part. That is not a reason to avoid the project, but it is a reason to read the licence files before you ship it inside a commercial product.

Apipie-rails compared with rswag and hand-written OpenAPI

The closest alternative in the Rails world is rswag, which takes the request-spec route: you describe endpoints inside RSpec or Swagger-style spec files and the documentation is generated from the test suite. The difference in approach matters more than the feature list. With Apipie-rails the documentation lives in the controller and can be reused for validation; with rswag the documentation lives in the test layer and is validated by the fact that the tests run. If your team already treats request specs as the contract, rswag fits that habit. If you want the controller to be the single place where a param is defined, declared and checked, Apipie-rails fits that one.

The other alternative is writing an OpenAPI document by hand and serving it. That gives you full control over the spec version and no Ruby in your controllers, at the cost of keeping the document in sync manually, which is exactly the drift problem Apipie-rails was built to avoid. A hybrid is possible: keep Apipie-rails as the authoring layer and consume /apipie.json in whatever pipeline you already have, which the README explicitly supports by exposing the documentation data as JSON.

Maintenance, upgrades and licence questions to settle

The repository is not archived, and the last push was on 2026-09-02. The release history shows v1.4.2 in July 2024, v1.5.0 in August 2025 and v1.5.1 in June 2026, so the project is still cutting releases, but the gaps between them are measured in months rather than weeks. Plan upgrades accordingly: read CHANGELOG.md before bumping the gem, and expect that a DSL change may require touching every annotated controller rather than one configuration file.

The upgrade cost is concentrated in the controllers. Because the DSL is Ruby code inside controller classes, a breaking change to a keyword or a validator surfaces as a load error or a failing spec rather than a silently stale document, which is the better failure mode. The documentation itself is generated at request time from the same declarations, so there is no separate build step to keep green unless you opt into static Swagger files.

On licensing, the README states MIT, the repository root carries MIT-LICENSE, APACHE-LICENSE-2.0 and NOTICE, and the project metadata lists Apache-2.0. The README does not reconcile these. Treat that as an open question to resolve with whoever handles licensing at your organisation rather than something to assume.

Editorial conclusion

Adopt Apipie-rails if your API lives in Rails controllers and you want the parameter definitions to sit next to the actions they describe, with /apipie and /apipie.json as the output. Do not adopt it if your API surface is not Rails controllers or if you need OpenAPI 3, since the README only documents static Swagger (OpenAPI 2.0) generation. Before committing, check the Swagger section's known limitations, decide whether the DSL belongs in controllers or in specs, and confirm the licence situation: the README says MIT while the repository ships both an MIT-LICENSE and an APACHE-LICENSE-2.0 file.

Frequently asked questions

Official sources

1. Apipie/apipie-rails on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases