GrapeSwagger::Entity

• What is grape-swagger-entity?
  • What it does
  • Example Output
• Related Projects
• Compatibility
• Installation
• Usage
  • Basic Entity
  • Custom Model Description
  • Entity References
  • Documentation Options
• Development
• Contributing
• License

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

• 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

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

• Grape
• Grape Entity
• Grape Swagger
• Grape Swagger Representable

This gem is tested with the following versions:

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

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

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

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

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

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

See testing documentation for development setup and running tests.

See contributing guidelines.

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