> For the complete documentation index, see [llms.txt](https://tonystrawberry.gitbook.io/rails-openapi-generator/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tonystrawberry.gitbook.io/rails-openapi-generator/getting-started/quick-start.md).

# Quick Start

This page walks you from a fresh gem install to a working OpenAPI document in under five minutes.

## 1. Install the gem

```ruby
# Gemfile
gem "rails-openapi-generator"
```

```sh
bundle install
```

## 2. Run the generator

```sh
bundle exec rake openapi:generate
```

The generator prints a summary and writes the spec:

```
OpenAPI document written to doc/openapi.json
  Processed: 42 endpoints
  Skipped:   1
    - GET /legacy (no backing controller action)
  Warnings:  0
```

The output file is `doc/openapi.json` by default. Re-runs produce byte-identical output — safe to commit and diff in CI.

## 3. Preview the spec

Open it in Redoc (no install needed):

```sh
npx @redocly/cli build-docs doc/openapi.json -o doc/openapi.html
open doc/openapi.html
```

Or use Swagger UI via Docker:

```sh
docker run --rm -p 8081:8080 \
  -e SWAGGER_JSON=/spec/openapi.json \
  -v "$PWD/doc:/spec" swaggerapi/swagger-ui
```

Then visit `http://localhost:8081`.

## 4. Document your first endpoint

Add a YARD comment and some `param!` calls to a controller action:

```ruby
class Api::UsersController < ApplicationController
  # List users
  # Returns all active users ordered by creation date.
  def index
    param! :page,     Integer, default: 1
    param! :per_page, Integer, in: 1..100, default: 25
    # ...
  end
end
```

Re-run `rake openapi:generate`. The `GET /api/users` operation will now have a summary, description, and two query parameters with their constraints.

## 5. Commit the spec to version control

```sh
git add doc/openapi.json
git commit -m "Add generated OpenAPI spec"
```

Add the generation step to your CI pipeline to catch drift:

```yaml
# .github/workflows/ci.yml (example)
- run: bundle exec rake openapi:generate
- run: git diff --exit-code doc/openapi.json
```

## Next step

[Configuration →](/rails-openapi-generator/getting-started/configuration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://tonystrawberry.gitbook.io/rails-openapi-generator/getting-started/quick-start.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.