Skip to content

Commit 87a807e

Browse files
numbatanumbata
committed
Improve README with comprehensive documentation
- Explain what the gem does and add example output - Add Related Projects section linking to grape ecosystem - Add Compatibility section with version table - Add usage examples for basic entities, custom descriptions, and references - Document all available documentation options - Expand table of contents with subsections - Add reference to CONTRIBUTING.md Fixes #58
1 parent 409d701 commit 87a807e

1 file changed

Lines changed: 115 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 115 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,62 @@
66
## Table of Contents
77

88
- [What is grape-swagger-entity?](#what-is-grape-swagger-entity)
9+
- [Related Projects](#related-projects)
10+
- [Compatibility](#compatibility)
911
- [Installation](#installation)
12+
- [Usage](#usage)
13+
- [Basic Entity](#basic-entity)
14+
- [Custom Model Description](#custom-model-description)
15+
- [Entity References](#entity-references)
16+
- [Documentation Options](#documentation-options)
1017
- [Development](#development)
1118
- [Contributing](#contributing)
1219
- [License](#license)
1320

14-
1521
## What is grape-swagger-entity?
1622

17-
A simple grape-swagger adapter to allow parse representers as response model
23+
This gem provides an adapter for [grape-swagger](https://github.com/ruby-grape/grape-swagger) that allows parsing [grape-entity](https://github.com/ruby-grape/grape-entity) classes to generate OpenAPI/Swagger model definitions automatically.
24+
25+
### What it does
26+
27+
- Generates `definitions` in your Swagger JSON from Grape::Entity exposures
28+
- Maps entity properties to OpenAPI schema properties with types and descriptions
29+
- Handles nested entities and entity references via `$ref`
30+
- Supports arrays, required fields, and documentation options
31+
32+
### Example Output
33+
34+
```json
35+
{
36+
"definitions": {
37+
"User": {
38+
"type": "object",
39+
"description": "User model",
40+
"properties": {
41+
"id": { "type": "integer", "description": "User ID" },
42+
"name": { "type": "string", "description": "Full name" }
43+
},
44+
"required": ["id", "name"]
45+
}
46+
}
47+
}
48+
```
49+
50+
## Related Projects
51+
52+
- [Grape](https://github.com/ruby-grape/grape)
53+
- [Grape Entity](https://github.com/ruby-grape/grape-entity)
54+
- [Grape Swagger](https://github.com/ruby-grape/grape-swagger)
55+
- [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
56+
57+
## Compatibility
58+
59+
This gem is tested with the following versions:
60+
61+
| grape-swagger-entity | grape-swagger | grape-entity | grape |
62+
|---------------------|---------------|--------------|---------|
63+
| 0.7.x | >= 1.2.0 | >= 0.6.0 | >= 1.3 |
64+
| 0.6.x | >= 1.2.0 | >= 0.6.0 | >= 1.3 |
1865

1966
## Installation
2067

@@ -32,17 +79,81 @@ Or install it yourself as:
3279

3380
$ gem install grape-swagger-entity
3481

82+
## Usage
83+
84+
### Basic Entity
85+
86+
Define your entities with `documentation` options to generate OpenAPI schema properties:
87+
88+
```ruby
89+
class UserEntity < Grape::Entity
90+
expose :id, documentation: { type: Integer, desc: 'User ID' }
91+
expose :name, documentation: { type: String, desc: 'Full name' }
92+
expose :email, documentation: { type: String, desc: 'Email address' }
93+
end
94+
```
95+
96+
### Custom Model Description
97+
98+
Override the default "{ModelName} model" description by defining a `self.documentation` method (requires grape-swagger >= 2.2.0):
99+
100+
```ruby
101+
class UserEntity < Grape::Entity
102+
def self.documentation
103+
{ desc: 'Represents a user account with profile information' }
104+
end
105+
106+
expose :id, documentation: { type: Integer, desc: 'User ID' }
107+
expose :name, documentation: { type: String, desc: 'Full name' }
108+
end
109+
```
110+
111+
### Entity References
112+
113+
Use `using:` to reference other entities and `is_array:` for collections:
114+
115+
```ruby
116+
class OrderEntity < Grape::Entity
117+
expose :id, documentation: { type: Integer, desc: 'Order ID' }
118+
expose :user, using: UserEntity,
119+
documentation: { desc: 'The customer who placed this order' }
120+
expose :items, using: ItemEntity,
121+
documentation: { desc: 'Line items', is_array: true }
122+
end
123+
```
124+
125+
### Documentation Options
126+
127+
The following options are available in the `documentation` hash:
128+
129+
| Option | Description |
130+
|--------|-------------|
131+
| `type` | OpenAPI data type (`String`, `Integer`, `Boolean`, etc.) |
132+
| `desc` | Property description |
133+
| `required` | Whether field is required (default: based on expose options) |
134+
| `is_array` | Marks field as array type |
135+
| `read_only` | Marks field as read-only |
136+
| `values` | Enum values for the field |
137+
| `example` | Example value |
138+
| `default` | Default value |
139+
| `minimum` | Minimum value for numeric types |
140+
| `maximum` | Maximum value for numeric types |
141+
| `min_length` | Minimum length for string types |
142+
| `max_length` | Maximum length for string types |
143+
| `hidden` | Hide field from documentation |
144+
35145
## Development
36146

37147
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/pry` for an interactive prompt that will allow you to experiment.
38148

39-
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
149+
To install this gem onto your local machine, run `bundle exec rake install`.
40150

41151
## Contributing
42152

43153
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-grape/grape-swagger-entity.
44154

155+
See [CONTRIBUTING](CONTRIBUTING.md) for more information.
156+
45157
## License
46158

47159
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
48-

0 commit comments

Comments
 (0)