AI Documentation

Docit can generate complete API documentation using AI. Works with OpenAI, Anthropic, or Groq (free tier available).

Quick start

The fastest way is through the install generator. When you run rails generate docit:install and choose option 1 (AI automatic docs), everything is set up automatically:

1. Asks which AI provider to use
2. Asks for your API key
3. Scans your routes for undocumented endpoints
4. Generates complete doc files in app/docs/
5. Injects use_docs into controllers
6. Adds tag descriptions to the initializer

Standalone commands

You can also set up AI docs separately after initial install:

# Configure your AI provider (one-time setup)
rails generate docit:ai_setup

# Generate docs for all undocumented endpoints
rails docit:autodoc

# Generate docs for a specific controller
rails docit:autodoc[Api::V1::UsersController]

# Preview what would be generated without writing files
DRY_RUN=1 rails docit:autodoc

Supported providers

All providers automatically retry on rate-limit (429) errors with exponential backoff, so free-tier usage works out of the box.

What the AI generates

For each undocumented endpoint, Docit:

1. Reads the controller source code
2. Inspects the route (HTTP method, path, parameters)
3. Writes a doc block to app/docs/ using the Docit DSL
4. Injects use_docs into the controller
5. Adds tag descriptions to the initializer

The generated docs use the separate doc file pattern, keeping controllers clean.

AI configuration file

AI configuration is stored in .docit_ai.yml at your Rails root. The file is created with restricted permissions (0600) and added to .gitignore automatically.

# .docit_ai.yml
provider: openai
api_key: sk-...

If your app does not have a .gitignore, add .docit_ai.yml manually to avoid committing your API key.

Safety considerations

Warning: Before the first AI request, Docit warns that your controller source code will be sent to the selected provider and asks for confirmation in interactive terminals.

Do not use AI autodoc on controllers that contain secrets, proprietary business rules, or internal comments you do not want sent to an external provider.

Dry run mode

Preview what would be generated without writing any files:

DRY_RUN=1 rails docit:autodoc

This runs the full AI pipeline but prints the output instead of writing files, so you can review before committing.

After generation

AI-generated docs are a starting point. You should:

• Review each generated file for accuracy
• Add missing edge cases or error responses
• Adjust examples to match your actual data
• Run your app and check /api-docs to verify everything looks right