Skip to content

ruby-grape/grape-swagger-entity

Repository files navigation

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"]
    }
  }
}

Related Projects

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.

About

No description, website, or topics provided.

Resources

License

Contributing

Stars

Watchers

Forks

Packages

No packages published

Contributors 26