README.md in rails_api_documentation-0.1.9 vs README.md in rails_api_documentation-0.2.0
- old
+ new
@@ -15,10 +15,17 @@
Or install it yourself as:
$ gem install rails_api_doc
+## Features
+
++ displaying application api if used in one of correct ways
+ 
++ Integration with Rabl if it is bundled
++ ```resource_params``` method that will filter incoming params for you
+
## Usage
To display api documentation on route '/api_doc' you need to:
1. config/routes.rb ->
@@ -47,14 +54,91 @@
parameter :test, type: String, required: true
end
```
-Parameter type may be one of these:
+## Strong params
+ You may want to use your defined request api to filter incoming parameters.
+ Usually we use something like `params.permit(:name, :age)`, but no more!
+ With this gem bundled you can do this:
+
```ruby
- ACCEPTED_TYPES = [Bool, String, Integer, Object, Array, DateTime, :enum, :model].freeze
+
+ parameter :body, type: :string
+ parameter :title, type: :string
+
+ # controller action
+ def create
+ Comment.create!(resource_params)
+ end
+
```
+
+ and if request is `POST '/comments', params: { body: 'Comment body', title: 'Comment title', age: 34 }`
+
+ Comment will be created with: `Comment(body='Comment body', title='Comment title', age=nil)`
+
+## Types
+
+ Parameter type may be one of these:
+
+ ```ruby
+
+ # Non nested
+ :bool - Boolean type, accepts true, false, 'true', 'false'
+ :string - will accept anything beside nested type
+ :integer - accepts numbers as string value, and usual numbers
+ :array - array of atomic values (integer, strings, etc)
+ :datetime - string with some datetime representation accepted by DateTime.parse
+ :enum - one of predefined values of enum: option (only atomic types)
+
+ # nested
+ :object - usual nested type. comes very handy with rails nested_attributes feature
+ :ary_object - array of :object type, rails nested_attributes on has_many
+
+ ```
+
+## TODO's
++ type for id reference with model field to display associated model and CONTROLLER in params for linking
+
++ native DSL for defining response
+```ruby
+ action :show do
+ response :age, type: Integer
+ response :name, type String
+ response :data, type: :model, model: Datum do
+ response :creation_date, type: DateTime
+ response :comment, type: String
+ end
+ end
+```
++ native DSL for defining scopes
+```ruby
+scope :age, desc: 'Filters authors by given age'
+```
++ dsl for extending response parameters
+```ruby
+ response :data, type: :model, model: Datum do
+ extends DataController, action: :show
+ end
+```
++ dsl for extending request parameters
+```ruby
+parameter :data, type: :model, model: Datum do
+ extends DataController, action: :show
+end
+```
++ ability to split request params to actions(low prior)
++ CRUD for all parameters
++ merging parameters from all sources before display
++ pull everything that's possible to config
+
+## Development
+
++ add specs for everything done
++ inline documentation
++ README FAQ on added functionality with examples
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).