Shared Schemas ($ref)

Define reusable schemas once and reference them across multiple endpoints. This keeps your docs DRY and produces clean $ref references in the OpenAPI spec.

Defining schemas

Add schema definitions in config/initializers/docit.rb or a dedicated file:

Docit.define_schema :User do
  property :id,    type: :integer, example: 1
  property :email, type: :string,  example: "user@example.com"
  property :name,  type: :string,  example: "Jane Doe"
  property :address, type: :object do
    property :street, type: :string
    property :city,   type: :string
  end
end

Docit.define_schema :Error do
  property :error,   type: :string, example: "Not found"
  property :details, type: :array, items: :string
end

Docit.define_schema :PaginationMeta do
  property :total, type: :integer, example: 42
  property :page,  type: :integer, example: 1
  property :per_page, type: :integer, example: 25
end

Using schemas in endpoints

Reference them with schema ref: inside response or request_body blocks:

doc_for :show do
  summary "Get user"
  tags "Users"

  parameter :id, location: :path, type: :integer, required: true

  response 200, "User found" do
    schema ref: :User
  end

  response 404, "Not found" do
    schema ref: :Error
  end
end

doc_for :create do
  summary "Create user"
  tags "Users"

  request_body required: true do
    schema ref: :User
  end

  response 201, "Created" do
    schema ref: :User
  end
end

What this generates

In the OpenAPI spec, Docit outputs:

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "email": { "type": "string", "example": "user@example.com" },
          ...
        }
      }
    }
  },
  "paths": {
    "/api/v1/users/{id}": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  }
}

Both Scalar and Swagger UI resolve $ref automatically, showing the full schema inline.

When to use shared schemas

• The same model appears in multiple endpoints (list, show, create, update)
• You want consistent property definitions across responses
• Error responses follow a standard format
• You're generating client SDKs and want clean type definitions

Tips

• Keep schemas in a dedicated initializer (e.g., config/initializers/docit_schemas.rb) for organization
• Schema names should match your model names for clarity
• You can still mix schema ref: with inline property definitions in different endpoints