ditkrg/schemable
4
0
Fork 0
mirror of https://github.com/ditkrg/schemable.git synced 2026-01-22 22:26:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Slightly Updates Readme

Browse Source
This commit is contained in:
Muhammad Nawzad 2023-11-14 23:04:36 +03:00
parent a832924ee5
commit ac5a10e113
No known key found for this signature in database
GPG Key ID: B954B6AAE33940B2
1 changed files with 35 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
README.md
View File

@ -20,17 +20,19 @@ Or install it yourself as:
## Usage
The installation command above will install the Schemable gem and its dependencies. However, in order for Schemable to work, you must also add the following files to your Rails application:
The installation command above will install the Schemable gem and its dependencies. However, in order for Schemable to work, you must also implement your own logic to use the generated schemas to feed it to RSwag.
- `app/helpers/serializers_helper.rb` - This file contains the `serializers_map` helper method, which is used to map a model to its serializer.
- `spec/swagger/common_definitions.rb` - This file contains the `aggregate` method, which is used to aggregate the schemas of all the models in your application into a single place. This file is recommeded, but not required. If you do not use this file, you will need to manually aggregate the schemas of all the models in your application into a single place.
-
To generate these files, run the following command:
The below are some command to generate some files to get you started:
```ruby
rails g schemable:install
```
This will generate `schemable.rb` in your `config/initializers` directory. This file will contain the configuration for the Schemable gem. You can modify the configuration to your liking. For more information on the configuration options, see the [Configuration](#configuration) section below.
### Generating Definition Files
The Schemable gem provides a generator that can be used to generate definition files for your models. To generate a definition file for a model, run the following command:
@ -41,7 +43,28 @@ rails g schemable:model --model_name <model_name>
This will generate a definition file for the specified model in the `lib/swagger/definitions` directory. The definition file will be named `<model_name>.rb`. This file will have the bare minimum code required to generate a schema for the model. You can then modify the definition file to your liking by overriding the default methods. For example, you can add or remove attributes from the schema, or you can add or remove relationships from the schema. You can also add custom attributes to the schema. For more information on how to customize the schema, see the [Customizing the Schema](#customizing-the-schema) section below.
## Customizing the Schema
### Configuration
The Schemable gem provides a number of configuration options that can be used to customize the behavior of the gem. The following is a list of the configuration options that are available:
| Option Name | Description | Default Value |
| ----------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------- |
| `orm` | The ORM that is used in the application. The options are `:active_record` and `:mongoid`. | `:active_record` |
| `timestamps` | Whether or not to include the `created_at` and `updated_at` attributes in the response schema. | `true` |
| `float_as_string` | Whether or not to convert the `float` type to a `string` type in the schema. | `false` |
| `decimal_as_string` | Whether or not to convert the `decimal` type to a `string` type in the schema. | `false` |
| `custom_type_mappers` | A hash of custom type mappers that can be used to override the default type mappers. A specific method should be used, see annex 1.0 for more information. | `{}` |
| `disable_factory_bot` | Whether or not to disable the use of FactoryBot in the gem. To automatically generate serialized instance. See annex 1.1 for an example. | `true` |
| `use_serialized_instance` | Whether or not to use the serialized instance in the process of schema geenration as type fallback for virtual attributes. | `false` |
| `custom_defined_enum_method` | The name of the method that is used to get the enum keys and values. This allows applications with the orm `mongoid` define a method that mimicks what `defined_enums` does in `activerecord. Please see annex 1.2 for an example. | `nil` |
| `enum_prefix_for_simple_enum` | The prefix to be used for the enum values when `mongoid` is used. | `nil` |
| `enum_suffix_for_simple_enum` | The suffix to be used for the enum values when `mongoid` is used. | `nil` |
| `infer_attributes_from_custom_method` | The name of the custom method that is used to get the attributes to be generated in the schema. | `nil` |
| `infer_attributes_from_jsonapi_serializable` | Whether or not to infer the attributes from the JSONAPI::Serializable::Resource class. | `false` |
### Customizing the Schema
The Schemable gem provides a number of methods that can be used to customize the schema. These methods are defined in the `Schemable` module of the gem. To customize the schema, simply override the default methods in the definition file for the model. The following is a list of the methods that can be overridden:
@ -51,10 +74,10 @@ The Schemable gem provides a number of methods that can be used to customize the
The list of methods that can be overridden are as follows:
| Method Name | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `serializer` | Returns the serializer class. |
| `attributes` | Returns the attributes that are auto generated from the model. |
| `relationships` | Returns the relationships in the format of { belongs_to: {}, has_many: {} }. |
|----------------------------------|------------------------------------------------------------------------------------------------------------|
| `serializer` | Returns the serializer class. Useful when `infer_attributes_from_jsonapi_serializable` is used |
| `attributes` | Returns the attributes that are auto generated from the model's fields/columns. |
| `relationships` | Returns the relationships in the format of { belongs_to: {}, has_many: {}, addition_to_included: {} }. |
| `array_type` | Returns the type of arrays in the model that needs to be manually defined. |
| `optional_request_attributes` | Returns the attributes that are optional in the request schema. |
| `nullable_attributes` | Returns the attributes that are nullable in the request/response schema. |
@ -66,7 +89,7 @@ The list of methods that can be overridden are as follows:
| `excluded_response_attributes` | Returns the attributes that are excluded from the response schema. |
| `excluded_response_relations` | Returns the relationships that are excluded from the response schema. |
| `excluded_response_included` | (not implemented yet) Returns the included that are excluded from the response schema. |
| `nested_relationships` | Returns the relationships to be further expanded in the response schema. |
| `serialized_instance` | Returns a serialized instance of the model, used for type generating as a fallback. |
| `model` | Returns the model class (Constantized from the definition class name). |
| `model_name` | Returns the model name. Used for schema type naming. |
| `definitions` | Returns the generated schemas in JSONAPI format (It is recommended to override this method to your liking) |
@ -184,12 +207,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/schemable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/schemable/blob/master/CODE_OF_CONDUCT.md).
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/schemable. This project is intended to be a safe, welcoming space for collaboration, and contributors. Please go to issues page to report any bugs or feature requests. Open issues are tagged with the `help wanted` label. If you would like to contribute, please fork the repository and submit a pull request.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the Schemable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/schemable/blob/master/CODE_OF_CONDUCT.md).