GrapeSwagger::Entity

Gem Version Build Status

Table of Contents

What is grape-swagger-entity?

This gem provides an adapter for grape-swagger that allows parsing grape-entity classes to generate OpenAPI/Swagger model definitions automatically.

What it does

  • Generates definitions in your Swagger JSON from Grape::Entity exposures
  • Maps entity properties to OpenAPI schema properties with types and descriptions
  • Handles nested entities and entity references via $ref
  • Supports arrays, required fields, and documentation options

Example Output

{
  "definitions": {
    "User": {
      "type": "object",
      "description": "User model",
      "properties": {
        "id": { "type": "integer", "description": "User ID" },
        "name": { "type": "string", "description": "Full name" }
      },
      "required": ["id", "name"]
    }
  }
}

Compatibility

This gem is tested with the following versions:

grape-swagger-entity grape-swagger grape-entity grape
0.7.x >= 2.0.0 >= 1.0.0 >= 1.3
0.6.x >= 1.2.0 >= 0.6.0 >= 1.3

Installation

Add this line to your application's Gemfile:

gem 'grape-swagger-entity'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-swagger-entity

Usage

Basic Entity

Define your entities with documentation options to generate OpenAPI schema properties:

class UserEntity < Grape::Entity
  expose :id, documentation: { type: Integer, desc: 'User ID' }
  expose :name, documentation: { type: String, desc: 'Full name' }
  expose :email, documentation: { type: String, desc: 'Email address' }
end

Custom Model Description

Override the default "ModelName model" description by defining a self.documentation method. This feature is handled by grape-swagger (requires grape-swagger >= 2.2.0):

class UserEntity < Grape::Entity
  def self.documentation
    { desc: 'Represents a user account with profile information' }
  end

  expose :id, documentation: { type: Integer, desc: 'User ID' }
  expose :name, documentation: { type: String, desc: 'Full name' }
end

Entity References

Use using: to reference other entities and is_array: for collections:

class OrderEntity < Grape::Entity
  expose :id, documentation: { type: Integer, desc: 'Order ID' }
  expose :user, using: UserEntity,
         documentation: { desc: 'The customer who placed this order' }
  expose :items, using: ItemEntity,
         documentation: { desc: 'Line items', is_array: true }
end

Documentation Options

Common options: type, desc, required, is_array, values, example.

See full documentation options for all available options including validation constraints.

Development

See testing documentation for development setup and running tests.

Contributing

See contributing guidelines.

License

The gem is available as open source under the terms of the MIT License.