<commit_before>Swaggard
========

Swaggard is a Rails Engine that can be used to document a REST api. It does this by generating a
json that is compliant with [Swagger](http://swagger.io) and displaying it using [Swagger-ui](https://github.com/wordnik/swagger-ui).
This gem is inspired and based on [SwaggerYard](https://github.com/synctv/swagger_yard) by [<NAME>](https://github.com/chtrinh). 
 
 
Swaggard vs SwaggerYard
-----------------------

The main reason this gem exists is to avoid having to write by hand some information and use what
rails already give us ie: controllers names and methods paths.

And also:
  - Bring support for Rails 4.
  - Bring support for Swagger 2.
  - Bring support for models (serializers).
  - Bring support for form and body params.
  - and more...


Installation
------------
  
Put Swaggard in your Gemfile:

    gem 'swaggard'

Install the gem with Bundler:

    bundle install


Getting Started
-----------------

Place your configuration in a your rails initializers
    
    # config/initializers/swaggard.rb

    Swaggard.configure do |config|
      config.api_version = '0.1'
      config.doc_base_path = 'http://swagger.example.com/doc'
      config.api_base_path = 'http://swagger.example.com/api'
    end

Mount your engine

	# config/routes.rb

	mount Swaggard::Engine, at: '/swagger'


Example
-------

Here is a example of how to use Swaggard

    # app/controllers/users/posts_controller.rb

    # User posts
    #
    # API for creating, deleting, and listing user posts.
    class User::PostsController < ActionController::Base

      # Returns the list of user posts
      #
      # @response_class Array<PostSerializer>
      def index
        ...
      end

      # Create user post
      #
      # @body_parameter [string] title
      # @body_parameter [string] body
      # @body_parameter [string] topic_id
      #
      # @response_class PostSerializer
      def create
        ...
      end

    end


    # app/serializers/post_serializer.rb

    # @attr [integer] id
    # @attr [string] title
    # @attr [string] body
    # @attr [date-time] created_at
    # @attr [date-time] updated_at
    # @attr [TopicSerializer] topic
    class PostSerializer < ActiveModel::Serializer

      attribute :id
      attribute :title
      attribute :body
      attribute :created_at
      attribute :updated_at

      has_one :topic, serializer: TopicSerializer

    end


    # app/serializers/topic_serializer.rb

    # @attr [integer] id
    # @attr [string] name
    # @attr [date-time] created_at
    # @attr [date-time] updated_at
    class TopicSerializer < ActiveModel::Serializer

      attribute :id
      attribute :name
      attribute :created_at
      attribute :updated_at

    end

![Web UI](https://raw.github.com/Moove-it/swaggard/master/example/web-ui.png)


Authentication<commit_msg>Update the sample image url<commit_after>Swaggard
========

Swaggard is a Rails Engine that can be used to document a REST api. It does this by generating a
json that is compliant with [Swagger](http://swagger.io) and displaying it using [Swagger-ui](https://github.com/wordnik/swagger-ui).
This gem is inspired and based on [SwaggerYard](https://github.com/synctv/swagger_yard) by [<NAME>](https://github.com/chtrinh). 
 
 
Swaggard vs SwaggerYard
-----------------------

The main reason this gem exists is to avoid having to write by hand some information and use what
rails already give us ie: controllers names and methods paths.

And also:
  - Bring support for Rails 4.
  - Bring support for Swagger 2.
  - Bring support for models (serializers).
  - Bring support for form and body params.
  - and more...


Installation
------------
  
Put Swaggard in your Gemfile:

    gem 'swaggard'

Install the gem with Bundler:

    bundle install


Getting Started
-----------------

Place your configuration in a your rails initializers
    
    # config/initializers/swaggard.rb

    Swaggard.configure do |config|
      config.api_version = '0.1'
      config.doc_base_path = 'http://swagger.example.com/doc'
      config.api_base_path = 'http://swagger.example.com/api'
    end

Mount your engine

	# config/routes.rb

	mount Swaggard::Engine, at: '/swagger'


Example
-------

Here is a example of how to use Swaggard

    # app/controllers/users/posts_controller.rb

    # User posts
    #
    # API for creating, deleting, and listing user posts.
    class User::PostsController < ActionController::Base

      # Returns the list of user posts
      #
      # @response_class Array<PostSerializer>
      def index
        ...
      end

      # Create user post
      #
      # @body_parameter [string] title
      # @body_parameter [string] body
      # @body_parameter [string] topic_id
      #
      # @response_class PostSerializer
      def create
        ...
      end

    end


    # app/serializers/post_serializer.rb

    # @attr [integer] id
    # @attr [string] title
    # @attr [string] body
    # @attr [date-time] created_at
    # @attr [date-time] updated_at
    # @attr [TopicSerializer] topic
    class PostSerializer < ActiveModel::Serializer

      attribute :id
      attribute :title
      attribute :body
      attribute :created_at
      attribute :updated_at

      has_one :topic, serializer: TopicSerializer

    end


    # app/serializers/topic_serializer.rb

    # @attr [integer] id
    # @attr [string] name
    # @attr [date-time] created_at
    # @attr [date-time] updated_at
    class TopicSerializer < ActiveModel::Serializer

      attribute :id
      attribute :name
      attribute :created_at
      attribute :updated_at

    end

![Web UI](https://raw.githubusercontent.com/Moove-it/swaggard/master/example/web-iu.png)


Authentication
{'fraction_non_alphanumeric': 0.10799512280090577, 'fraction_numerical': 0.0013934854554955582, 'mean_word_length': 2.564245810055866, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 7, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2664838', 'n_tokens_mistral': 1749, 'n_tokens_neox': 1666, 'n_words': 527}