Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mberlanda/jsonschema_serializer

The gem is to generate JsonSchema
https://github.com/mberlanda/jsonschema_serializer

jsonschema jsonschema-generator ruby serialization

Last synced: 3 months ago
JSON representation

The gem is to generate JsonSchema

Awesome Lists containing this project

README 

        
# JsonschemaSerializer



[![Build Status](https://travis-ci.org/mberlanda/jsonschema_serializer.svg?branch=master)](https://travis-ci.org/mberlanda/jsonschema_serializer)

[![Gem Version](https://badge.fury.io/rb/jsonschema_serializer.svg)](https://badge.fury.io/rb/jsonschema_serializer)

[![Maintainability](https://api.codeclimate.com/v1/badges/7312071a0865c70f5d60/maintainability)](https://codeclimate.com/github/mberlanda/jsonschema_serializer/maintainability)

[![Test Coverage](https://api.codeclimate.com/v1/badges/7312071a0865c70f5d60/test_coverage)](https://codeclimate.com/github/mberlanda/jsonschema_serializer/test_coverage)



This purpose of this gem is to generate [JsonSchema](http://json-schema.org/).

This can be achieved with a builder class or an `ActiveRecord` wrapper.

The gem is available for both Rails 4, 5 or in Ruby standalone projects.



Since the project is still at an early stage, please do not hesitate to [open issues / feature requests](https://github.com/mberlanda/jsonschema_serializer/issues) or fork this repo for pull requests.



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'jsonschema_serializer'

```



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install jsonschema_serializer



## Usage



You can generate a schema as follows:



```ruby

schema = JsonschemaSerializer::Builder.build do |b|



  subscriber = b._object title: :subscriber, required: [:age] do |prop|

    prop.merge! b.string :first_name, title: 'First Name'

    prop.merge! b.string :last_name, title: 'Last Name'

    prop.merge! b.integer :age, title: 'Age'

  end



  b.title "a title"

  b.description "a description"

  b.required :a, :b, :c

  b.properties.tap do |p|

    p.merge! b.string :a, description: "abc"

    p.merge! b.array :subscribers, description: "subscribers", items: subscriber

  end

end



schema.to_json

```



Allowed parameters for data types:



- `array`  : `:default, :description, items: {}||[{}], :minItems, :maxItems, :title`

- `boolean`: `:default, :description, :title`

- `integer`: `:default, :description, enum: [], :minimum, :maximum, :multipleOf, :title`

- `number` : `:default, :description, enum: [], :minimum, :maximum, :multipleOf, :title`

- `string` : `:default, :description, :format, :minLength, :title`



You can alternatively use an experimental builder for `ActiveRecord`



```ruby

serializer = JsonschemaSerializer::ActiveRecord



schema = serializer.from_model(MyActiveRecordClass)

schema = serializer.from_model(MyActiveRecordClass, only: %[desired1 desired2])

schema = serializer.from_model(MyActiveRecordClass, except: %[ignored1 ignored2])



# You can manipulate the resulting schema



schema.tap do |s|

  s.title "a title"

  s.description "a description"

end



schema.to_json

```



## Rails



At this stage, a first usage within a Rails application could be a rake task dumping the schemas inside the public folder.



```ruby

# lib/tasks/jsonschemas.rake

require 'fileutils'



task dump_jsonschemas: :environment do

  Rails.application.eager_load!

  models = ActiveRecord::Base.descendants



  output_path = Rails.root.join('public', 'data')

  # Ensure that the destination path exists

  FileUtils.mkdir_p(output_path)



  models.each do |model|

    # Skip abstract classes

    if model.table_name

      file_path = output_path.join("#{model.model_name.param_key}.json")

      schema = JsonschemaSerializer::ActiveRecord.from_model(model)



      puts "Creating #{file_path} ..."

      File.open(file_path, 'w') { |f| f.write(schema.to_json) }

    else

      puts "Skipping abstract class #{model.to_s} ..."

    end

  end

end



```



## Development



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



In order to test against serveral ruby and rails versions, you can simply run `scripts/run_all_tests`. In the gnome-terminal you may need to run `/bin/bash --login scripts/run_all_test`.



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).



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/mberlanda/jsonschema_serializer.

Please ensure to keep the test coverage at 100% and follow the angularjs [commit message conv.entions](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#subject-line).